Note: See rules and conditions for API use
API is always prefixed with v3
This is for advanced use-cases. Most users will do queries through the portal which allows creation of dashboards, maps and the managing of large data sets.
Entities are things like water points, sanitation facilities, water tests, etc. Basically, any record that should be tracked through time.
They act as database tables, but with several additions:
_id - UUID v4 id. Can be generated with node-uuid by calling v4()
_created_on - date/time ISO 8601 that it was created
_created_by - username who created it
_managed_by - user/group that entity is managed by. E.g. "group:somegroupid", "user:someuserid"
_roles - (created dynamically from entity_roles.xyz table where xyz is entity type). Array of { role: permission, to: role name (e.g. "all", "user:john", etc.) }
_id - uuid of the entity type
code - human-readable unique code. Also name of the table in the database
name - localized name of entity type (e.g. { _base: "en", en: "cat", fr: "chat" })
You can get a list of all entity types at: https://api.mwater.co/v3/entity_types
The code (e.g. "water_point", or "sanitary_inspection") is the important field for accessing it.
There is a collection called groups which list all groups (organizations, branches, teams and legacy groups)
https://api.mwater.co/v3/groups
Fields are:
_id: uuid of group
_rev: revision, server-set
name: name of the group
desc: description of groups
public: true if group is publically visible
canManageEntities: true if group can manage entities
access_code: access code to join group
created: contains on which is the timestamp and by which is the user _id
modified: contains on which is the timestamp and by which is the user _id
type: organization_head (head of organization), organization (branch of organization), staff (team of branch), normal (legacy group)
parentname: name of parentage of organization
staff_role: set if admin, viewer or manager special groups
ancestry: parentage _id including self
To query an entity collection:
https://api.mwater.co/v3/entities/ENTITY_CODE?filter=JSON_MONGO_STYLE_FILTER&client=CLIENTID&limit=LIMIT
client id is the token received when logging in to the system. See Login section below.
Query options are:
filter: MongoDB-style selector. Omit to see all records. MongoDB-style query selectors and sort orders
sort: MongoDB-style sort order. e.g. ["_created_on"] to sort by creation date
limit: Maximum documents to return
fields: projection to use restricting fields returned. e.g. {"name": 1}
For example:
https://api.mwater.co/v3/entities/water_point?limit=10
Gets the first 10 water points.
https://api.mwater.co/v3/entities/water_point?filter={"code":"10007"}
Gets the water point with code "10007".
Properties are like columns for an entity type. They are listed at https://api.mwater.co/v3/properties
To get a list for a particular entity type: https://api.mwater.co/v3/properties?filter={"entity_type":"water_point_functionality_report"}
Properties have the following structure:
_id - uuid of the property
type - text, decimal, integer, enum, boolean, image, imagelist, json, geometry, measurement, date, entity
code - human-readable unique name per entity type. Also column name
name - localized name of property (e.g. { _base: "en", en: "cat", fr: "chat" })
values - values of enum. e.g. [{ code: "yes", name: { _base: "en", en: "Yes", fr: "Oui"}}, { code: "no", name: { _base: "en", en: "No", fr: "Non"}}]
units - (deprecated) units of measurement e.g. ['cm', 'm', 'ft']
entity_type - type code of the entity
text - string
decimal - floating point number
integer - integer
enum - fixed set of values. see values field for the list. stored as a text field containing the id of the enum value
geometry - retrieved and set as GeoJSON. Stored as geometry PostgreSQL type
date - ISO 8601 date: YYYY-MM-DD
entity - _id of referenced entity
measurement - (deprecated) magnitude and unit. Stored as json field { magnitude: number, unit: code of unit }
image - single image with optional caption. Stored as json field { id: id of image, caption: optional string caption }.
Images can be retrieved at https://api.mwater.co/v3/images/IDOFIMAGE?h=OPTIONALHEIGHT
imagelist - array of images
json - plain JSON
Units are the units of measurement for properties of type measurement.
To see complete list: https://api.mwater.co/v3/units
Each entity has a _roles field that gives permission to roles to do certain actions
view - can view entity
limited - (deprecated) can view entity, except for limited properties. Limited properties are nulled or substituted with another property depending on limited_subst
edit - can edit entity, but not change roles or delete
admin - can edit, change roles or delete
To create a new entity, POST to https://api.mwater.co/v3/entities/ENTITY_TYPE?client=CLIENTID
entity type is the entity type code, e.g. water_point
client id is the token received when logging in to the system. See Login section below.
The POST should have a plain text body of JSON of the single entity to update. e.g. POST to
https://api.mwater.co/v3/entities/water_point?client=2dcfd1e031684a3f88c70bb3a058aa9e (sample client id only)
the plain JSON body of:
{
"_id": "e921c4d2-b516-456a-9f82-f2e4ee925156",
"name": "My Test Water Point",
"desc": "My Test Water Point Description",
"type": "Protected dug well",
"location": { "type": "Point", "coordinates": [12, 95] },
"_roles": [{ "id": "user:aedb19d028c841ab84d9c15052ad7a63", "role": "admin" }],
"_managed_by": "user:aedb19d028c841ab84d9c15052ad7a63"
}
Note that _id and code do not need to be set on insert. The server will automatically add them and return the complete entity.
code is a special unique value that is generated on the server. It cannot be changed for an entity.
_managed_by must be set and should be set to the same user/group that has admin rights.
_roles should either contain one admin (for private entities) or one admin and all for protected entities or all for public
e.g.
Private: [{ "id": "user:aedb19d028c841ab84d9c15052ad7a63", "role": "admin" }]
Protected: [{ "id": "user:aedb19d028c841ab84d9c15052ad7a63", "role": "admin" }, { "id": "all", "role": "view" }]
Public: [{ "id": "all", "role": "admin" }] (in this case, _managed_by should be "all")
In the case of users, the _id of the user must be used, not the username.
In the case of groups, the _id of the group must be used, not the group name.
Groups are can be listed at https://api.mwater.co/v3/groups Add ?client=CLIENTID to see private ones.
Required fields are:
_id (set automatically), code (set automatically), location, _roles, _managed_by.
To update an entity, either POST the complete entity to https://api.mwater.co/v3/entities/ENTITY_TYPE?client=CLIENTID
This will not duplicate the entity, but rather update it.
Alternatively, PATCH the changes to https://api.mwater.co/v3/entities/ENTITY_TYPE/ENTITY_ID?client=CLIENTID
The PATCH should have a plain text body of JSON of before and after change:
{
"doc": {
"_id": "e921c4d2-b516-456a-9f82-f2e4ee925156",
"name": "My Test Water Point's New name",
"desc": "My Test Water Point Description",
"type": "Protected dug well",
"location": { "type": "Point", "coordinates": [12, 95] }
},
"base": {
"_id": "e921c4d2-b516-456a-9f82-f2e4ee925156",
"name": "My Test Water Point",
"desc": "My Test Water Point Description",
"type": "Protected dug well",
"location": { "type": "Point", "coordinates": [12, 95] }
}
}
To delete an entity, DELETE to https://api.mwater.co/v3/entities/ENTITY_TYPE/ENTITY_ID?client=CLIENTID
200 on success, otherwise error code.
Localized names in the database have a key for each language (e.g. en: "Apple", fr: "Pomme") plus a _base key to indicate original language: { _base: "en", en: "Apple", fr: "Pomme" }
Images are stored separately and can be downloaded by their id as referenced in image fields.
E.g. https://api.mwater.co/v3/images/134d39b273274e86a8e0e0d5cbe53920
Thumbnails of various sizes (160, 320, 640, 1280 pixels high) are available. Height parameter "h" will be rounded up to nearest available:
E.g. https://api.mwater.co/v3/images/134d39b273274e86a8e0e0d5cbe53920?h=320
To login, POST username and password to https://api.mwater.co/v3/clients as the body in plain JSON (application/json)
You will receive a client id which should be appended as the query parameter "client" to all requests.
To logout, DELETE https://api.mwater.co/v3/clients/CLIENT_ID_HERE
The client id is valid indefinitely.
You can ping the API to test connectivity by doing a GET, PUT, PATCH or POST to ping. It will reply with the text string ping
Advanced queries which join multiple tabls are possible in a SQL-like languange called JsonQL. Please contact us at development@mwater.co if you need to perform a more complex query.
Assignments are requests for a user, users or groups to complete a specifc form, usually with information in the form response pre-filled.
For example, a user could be given an assignment to fill out form X and when they start the survey, it has questions A, B and C prefilled with the known values.
Each assignment has the following fields:
_id: uuid of assignment
_rev: revision, server-set
form: form _id of the form that the assignment is for
deployment: deployment _id that the assignment is for
name: optional name of the assignment. Text.
cluster: optional cluster name. Text. Free text that groups assignments
location: optional GeoJSON location of the assignment. If set, will give directions to the user
data: form data to prefill. Matches the structure of response data exactly. Since this structure is complex, it is best to import an example
in the portal and view network traffic to capture the contents. Then use that as a template. Or, given an "ideal" response, query the response
at https://api.mwater.co/v3/responses/RESPONSE_ID_HERE?client=CLIENT_ID_HERE. Then view the data field.
assignedTo: array of subjects to assign to. e.g. ["group:SOME_GROUP_ID", "user:SOME_USER_ID"]. Blank for unassigned.
roles: will be set automatically on the server
created: contains on which is the timestamp and by which is the user _id. Set automatically
modified: contains on which is the timestamp and by which is the user _id. Set automatically
To query assignments:
https://api.mwater.co/v3/assignments?filter=JSON_MONGO_STYLE_FILTER&client=CLIENTID&limit=LIMIT
client id is the token received when logging in to the system. See Login section above.
Query options are:
filter: MongoDB-style selector. Omit to see all records. MongoDB-style query selectors and sort orders
sort: MongoDB-style sort order. e.g. ["name"] to sort by name
limit: Maximum documents to return
fields: projection to use restricting fields returned. e.g. {"name": 1}
To upsert, POST to:
https://api.mwater.co/v3/assignments?client=CLIENTID
with the plain JSON body of the assignment to upsert
To delete an assignment, DELETE to https://api.mwater.co/v3/assignments/ASSIGNMENT_ID?client=CLIENTID
200 on success, otherwise error code.