Home

The Open Concept Lab API is an open definition for collaborative management of health terminology and indicators, which are collectively referred to as "concepts". The API supports searching and concepts, building "sources" (a.k.a. data dictionaries), and subsetting concepts into "collections". Social features such as sharing, following, etc. are planned for subsequent phases. This is the Technical Documentation for the API. The OCL Web Client is available at https://github.com/OpenConceptLab/ocl_web/. A cloud-based instance of OCL is available at http://www.openconceptlab.org.

Implementation Notes

• All dates should follow ISO 8601 and be in UTC. Ex: 2011-11-16T14:26:15Z
• All field/properties should follow the underscore_spacing convention
• All URL parameters follow are in camelCase
• All URL references within JSON are relative. For example, use /orgs/WHO/sources/ICD-10-2010/ instead of http://api.openconceptlab.com/orgs/WHO/sources/ICD-10-2010/
• Use UTF-8 encoding

API Endpoint

• http://api.openconceptlab.org/

OCL REST Resources

The API exposes the following resources:

• users - OCL user
• orgs - Group of one or more users that can own sources and collections SNOMED, indicator repository e.g. WHO Indicator and Measurement Registry)
• sources - Any source of concepts/terms/indicators (OpenMRS dictionary, reference dictionary e.g. ICD-10
• collections - References to concepts contained in one or more sources
• concepts - A term, definition, indicator, quality measure, etc.
• mappings - A mapping between 2 concepts of the same or different sources

Pagination and Limiting the Number of Returned Results

Which results are returned can be controlled using the limit and offset parameters as follows:

• limit - default=20; set the number of results returned in a request. Set limit=0 to return all results.
• page - default=1; set the page number of the results returned

Examples:

# Fetch the first 10 results
GET /concepts?q=malaria&limit=15

# Fetch the next 10 results
GET /concepts?q=malaria&limit=10&page=2

Sorting

Results may be sorted based on a single field using the sortAsc and sortDesc parameters. Note that not all fields support sorting. The documentation for each resource indicates which fields are supported.

• sortAsc - sort ascending
• sortDesc - sort descending

Examples:

GET /sources/?sortAsc={property1}
GET /sources/?sortDesc={property1}

Filters

• Results may be filtered by many fields using the {field_name}={value}[,{value}[,{value}[...]] parameter. Filters may be combined. A comma-separated list may be used to specify more than one option for a single filter. For example, datatype=Date,Datetime will match concepts with datatypes of "Date" or "Datetime". Read the documentation for each resource for information about which field-level filters are supported.

Examples:

# Match concept datatype of Numeric OR Text
GET /concepts/?datatype=Numeric,Text

# Match source type of Dictionary
GET /sources/?sourceType=Dictionary

• Results may also be filtered by certain common metadata, such as updatedSince. Refer to each resource for additional metadata filters.
  • updatedSince - ISO 8601 timestamp (e.g. 2011-11-16T14:26:15Z)

Example:

GET /orgs/Columbia/sources/CIEL/concepts/?updatedSince=2014-11-16T14:26:15Z

Facets

• Certain fields are implemented as facets, which means that the API will optionally return the possible options for a field along with search results. To turn on facets, add "includeFacets: true" to the request header.

GET /concepts/?q=malaria&includeRetired=true

{
    "facets": {
        "fields": {
            "retired": {
                "0": {
                    "0": "false",
                    "1": "44"
                },
                "1": {
                    "0": "true",
                    "1": "8"
                }
            },
            "conceptClass": {
                "0": {
                    "0": "Diagnosis",
                    "1": "42"
                },
                "1": {
                    "0": "Misc",
                    "1": "4"
                },
                "2": {
                    "0": "Question",
                    "1": "4"
                },
                "3": {
                    "0": "Misc Order",
                    "1": "1"
                },
                "4": {
                    "0": "Test",
                    "1": "1"
                },
                "5": {
                    "0": "Aggregate Measurement",
                    "1": "0"
                },
                "6": {
                    "0": "Anatomy",
                    "1": "0"
                }
            }
        }
    },
    "results": {
        # Results are included here
    }

Resource Representations

Resources are returned in either detail or summary view:

• detail - Detailed view is returned when fetching a single object, or when verbose is set to true
• summary - Summary view is returned when fetching a list of objects

Common Attributes

• Audit Info - all resources have the following audit fields:
  • created_by - username of the user that created the object
  • created_on - timestamp at which object was created
  • updated_on - username of the user that most recently updated the object
  • updated_by - timestamp at which object was most recently updated
• Additional common attributes (not necessarily shared by all resources)
  • uuid - Universally unique identifier for the resource
  • url - RESTful URL to the resource
  • display - Preferred display name based on current locale (default 'en')
  • display_locale - Locale of the display name
  • retired - Retired status of the resource (true/false)
  • extras - Optional dictionary of additional resource properties

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
• 204 No Content - Indicates that the request was received and that no content was returned
• 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 a conflict in the operation was detected and the operation was not performed.
• 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 return 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 message (for debugging and/or display purposes), For example, for a call with when the resource is not found:

Status: 404 Not Found

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

Response Formats

• JSON is the only supported format and an error occurs if an unsupported format is requested.
• The "compress=true" header may be applied to any request to receive a zipped file of the JSON results. This is especially useful for exporting the results of a list query (e.g. GET /concepts/).

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.

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