About the Facility Registry

The Facility Registry API is an open standard for sharing and updating health facility data.

To follow or contribute to the discussion related features in the API: see facility registry github issues.

The API is an ongoing collaborative effort begun under the Open Facility Registry Service Project: Facility Registry Expansion Development (FRED).

This project is supported by PEPFAR and USAID

 

Implementation Notes
  • All dates should follow ISO 8601 and be in UTC. Ex) 2011-11-16T14:26:15Z
  • All field/properties should follow the camelCasing convention
  • Use UTF-8 encoding

RECOMMENDED PRACTICES

  • While it is not required, we suggest implementations support gzip, etags and cache headers which can help reduce unnecessary data transfer which is helpful in low-bandwidth environments.
  • Cache headers if implemented could be especially useful, as a common use case seems to be maintaining a mirror of facility information.

HTTP Response Codes

HTTP Status Codes

  • 200 OK - All Indicates that the specified action was successfully completed. A 200 response indicates that the registry did successfully perform the operation and the response contains the final result of the action.
  • 201 Created - Indicates that a request was successful and as a result, a resource has been created
  • 400 Bad Request - Indicates that the requested operation is not valid.
  • 401 Unauthorized - Raised when the client attempts to perform an operation against a resource which requires authorization. This error code indicates a challenge for client credentials.
  • 403 Forbidden - Indicates that the client does not have the necessary permission to perform the specified operation against the requested resource.
  • 404 Not Found - Indicates that a resource was not found or is not available.
  • 405 Not Allowed - Indicates that the requested operation is not allowed on the current resource (for example: DELETE on a collection)
  • 409 Conflict - Indicates that the facility registry has detected a conflict in the operation and has refused to perform the operation.
  • 410 Gone - Indicates that a resource did exist but has been permanently removed.
  • 500 Internal Server Error - Indicates that the server encountered an error while attempting to execute the desired action.

Success

Success differ from errors in that their body may not be a simple response object with a code and a message. The headers however are consistent across all calls:

  • GET, PUT, DELETE returns 200 OK on success,
  • POST returns 201 Created on success,

Error

Error responses are simply returning standard HTTP error codes along with some additional information:

  • The error code is sent back as a status header,
  • The body includes an object describing both the code and OPTIONALLY the message

For example, for a call with when the resource is not found:

Status: 404 Not Found { code: 404 Not Found, message: 'Resource not found' }

Authentication

Authentication is handled by HTTP Basic Authentication.

Every API request must include a valid authentication token in the header.

The Authorization header is constructed as follows:

  • Username and password are combined into a string “username:password”
  • The resulting string literal is then encoded using Base64
  • The authorization method and a space i.e. “Basic ” is then put before the encoded string.

For example, if the user agent uses ‘Aladdin’ as the username and ‘open sesame’ as the password then the header is formed as follows:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Versioning

API Documentation follows semantic versioning

API documentation revisions will be assigned a unique version number in the format MAJOR.MINOR.REVISION. These version numbers follow semantic versioning pattern whereby:

  • REVISION is incremented for revisions to a MINOR version. These changes represent nonfunctional changes to the API.
  • MINOR version numbers are incremented when new functionality is introduced which is backwards compatible with existing functionality in the MAJOR version. MINOR versions numbers are semantically compatible with previous MINOR versions.
  • MAJOR version numbers are incremented when new functionality is introduced which is semantically incompatible with previous versions.

/api/v1/facilities.json

All prior versions still supported by the code should be exposed by its own URL.

Facility Object

The API exposes a representation of the health facilities in JSON.

EXAMPLE HEALTH FACILITY RESPONSE

{ "facilities": [ { "name": "Kakamega HC", "href": "http://facilityregistry.org/api/v1/facilities/53adf.json", "uuid": "550e8400-e29b-41d4-a716-446655440000", "active": true, "createdAt": "2011-11-16T14:26:15Z", "updatedAt": "2011-11-16T14:26:15Z", "coordinates": [ -1.6917, 29.525 ], "identifiers": [ { "agency": "MOH", "context": "DHIS", "id": "123" }, { "agency": "UNICEF", "context": "mtrac", "id": "53adf" } ], "properties": { "numBeds": 55, "services": [ "XR", "OBG", "TR" ], "equipment": [ { "id": 542, "name": "Microscope" }, { "id": 942, "name": "Vaccine Fridge" } ], "manager": "Mrs. Liz", "hasMaternity": true, "medicalOfficer": "Dr.Mukombo" } } ] }

Core Properties

Each facility has the following core properties:

  • name - Name of the facility.

"name": "Kakamega HC"

  • uuid - globally unique UUID per RFC 4122. The UUID for a facility should remain constant and should never be changed. eg) the URL of the facility changes.

"uuid": "50e8400-e29b-41d4-a716-446655440000"

  • href - URL link to the unique ID API resource for the facility. The url of a facility MAY be structured around the uuid, a system-specific identifier or some other scheme. Clients of the facilities registry MUST use the provided url field and not attempt to calculate the URL themselves from other fields the facility has.

Using the same HREF should always return the same facility (if it still exists).

"href": "http://facilityregistry.org/api/v1/facilities/53adf.json"

FACILITY IDENTIFIERS

One of the primary functions of the facility registry is to facilitate a mapping of the different IDs used by different agencies to represent a particular facility.

Each external identifier consists of the following components:

agency: agency who created the code. ex) ministry of health, UNICEF, etc. context: context/external system in which the agency is using the ID. eg) HMIS, DHIS2, HR id: unique identifier

"identifiers": [ {"agency": "MOH", "context": "DHIS", "id": "123"}, {"agency": "UNICEF", "context": "mtrac", "id": "53adf"}, { .... } ]

  • coordinates - Geolocation represented by longitude and latitude coordinates in that order. All coordinates assume as WSG84 projection.

"coordinates": [lng, lat]

  • active - indicates whether the facility is active or not.

"active": {true/false}

  • createdAt - ISO 8601 timestamp of when the facility was created in the registry.

"createdAt": "2011-11-16T14:26:15Z"

  • updatedAt - ISO 8601 timestamp of when the facility was last updated in the registry.

"updatedAt": "2011-11-18T16:26:15Z"

Extended Properties

Extended properties are implementation specific properties in the properties block.

The property types that are supported are:

  • String – A series of textual characters

  • Integer – A whole number

  • Decimal

  • Boolean – A true or false value

  • Date: ISO 8601 format. eg) 2012-12-16T18:22:20Z

  • Lists - A list of one of the following data types

    • Simple data types such as the code mnemonic of selected value(s) (example: “apple”,”orange”)
    • Implementation specific complex data

SAMPLE PROPERTIES

"properties": { "numBeds": 55, "services": ["XR","OBG","TR"], "equipment": [ { "id": 542, "name": "Microscope" }, { "id": 942, "name": "Vaccine Fridge" } ], "manager": "Mrs. Liz" "hasMaternity": true, },

Property field specification expectations

  • For each property field, the implementer specifies a stable code that should not be changed once defined. The implementation should warn the user if they attempt to modify the code.
  • The property field code should consist only of letters and numbers and not any special characters, spaces or punctuation to allow them to represent a good xml element. The API does not specify whether to define properties using camelCasing or lower_case, however, we encourage the implementation to be consistent in their formating.
  • Each property field should be unique
  • Specific properties for attachments and images are not supported in this version. It is possible to use a text string to represent a file path but that is implementation specific

GET /facilities.json Get facilities

Request Parameters

  • allProperties - boolean field (default true) specifying that all the core and extended properties should be returned.

/facilities.json?allProperties={true/false}

SORTING

  • sortAsc - Sort ascending
  • sortDesc - Sort descending

/facilities.json?sortAsc={property1}

Sorting is currently limited to one field

PAGINATION

  • limit - Number of records to return in a result. Default = 25
  • offset - Offset of the search result. Default = 0
  • limit=off - Disables pagination. Pagination on by default.

/facilities.json?limit=25&offset=50

PARTIAL RESPONSE

  • fields - specifies which fields should be returned in the response.

/facilities.json?fields=name,id,properties:numBeds

This would return just the specified properties of name, id and numBeds (in the properties sub-object) in a partial response. This is very helpful in optimizing performance in bandwidth constrained settings. All properties in the facility registry are accessible by this method including the core properties and those in the property sub-object.

FILTERING FACILITIES

  • {propertyName} - name of the property you want to filter by

/facilities.json?{propertyName}={filterValue}

  • Supports only exact matches of the filter value
  • One value per instance of parameter
  • Name of a parameter must exactly match the name of the property (core or extended) on which it filters data
  • Instances of the same parameter are OR and different are AND. For example: ?properties:services=OBG&properties:services=ER would filter all facilities offering OBG OR ER, where as ?identifiers:id=2030&identifiers:agency=MOH would filter facilities with an identifier 2030 AND identifier assigned by MOH.

FILTER BY ACTIVE STATUS

  • active - filter facilities based on whether they are active or not.

/facilities.json?active={true/false}

FILTER BY UPDATED SINCE

  • updatedSince - return facilities updated since a particular date expressed in ISO 8601 format.

/facilities.json?updatedSince=2011-11-16T00:00:00Z

Response

Status: 200 OK Returns a collection of facilities

For errors responses, see the response status codes documentation.

GET /facilities/{id}.json Get a facility

Get an individual facility for a particular id.

Request

  • {id} of the facility

Response

Status: 200 OK

{ "facility": { "name": "Kakamega HC", ... }

Returns the facility object matching {id} including core and extended properties.

Status: 404 Not Found { code: 404 Not Found, message: 'Resource not found' }

Facility resource not found or unavailable

For errors responses, see the response status codes documentation.

POST /facilities.json Create a facility

Create a new facility

Request

  • The name attribute representing the name of the facility is mandatory.
  • by default active=true
  • the uuid can be passed from the client. If not, it will be generated by the registry service.

{ name: "Kakamega HC" }

Response

Returns the created facility, in the same format as a default GET of the individual facility.

Status: 201 Created Location: http://facilityregistry.org/api/v1/facilities/53adf.json

{ "name": "Kakamega HC", ... }

Returns the facility object of the newly created facility.

Duplicate

If duplicate is detected a 409 is returned

Status: 409 Conflict

For errors responses, see the response status codes documentation.

PUT /facilities/{id}.json Update a facility

Update the facility, replacing the facility properties with the new resource representation passed in the request.

Request

  • Full new resource representation of the facility (not a partial update)
  • The body can’t be empty and must include at least the name attribute, a string that will be used as the name of the facility.
  • The id, url, createdAt, and updatedAt core properties cannot be changed by the client. An update request including any of these properties or any unknown core properties should result in a 400 Bad Request error.

{ name: 'Kakamega HCII' }

Response

Returns the location of the updated facility.

Status: 200 OK Location: http: //facilityregistry.org/api/v1/facilities/0X9OCW3JMV98EYOVN32SGN4II.json

{ "facility": { "name": "Kakamega HC", ... }

Returns the facility object of the updated facility.

Not Found

If the the facility resource is not found to update

Status: 404 Not Found { code: 404 Not Found, message: 'Resource not found' }

For errors responses, see the response status codes documentation.

DELETE /facilities/{id}.json Delete a facility

Delete a facility

Request

  • {id} of the facility to delete.
  • The body is omitted.

Response

If the facility resource is found and deleted

Status: 200 OK

{ code: 200, id: '0X9OCW3JMV98EYOVN32SGN4II' message: 'Resource deleted' }

If facility resource for id is not found

Status: 404 Not Found { code: 404 Not Found, message: 'Resource not found' }

Note: The facility registry SHALL delete the facility resource such that the record is no longer discoverable to consumers. The process by which the facility registry marks the facility as deleted is not specified in this document, and is left to implementers to determine the most appropriate method.

For errors responses, see the response status codes documentation.