Skip to content
This repository has been archived by the owner on Aug 11, 2021. It is now read-only.

Quick Reference

Jump to bottom
Jonathan Payne edited this page Feb 25, 2015 · 3 revisions

Quick Reference is the under development version of the API specification that uses a GitHub style modeling in which all sources and collections are owned by users and organizations. Refer to Quick Reference v0.2 and Quick Reference v0.1 for other versions of the API specification.

Overview

The Open Concept Lab API is an open definition for searching concepts and sharing and updating data dictionaries. A cloud-based instance will be available at http://www.openconceptlab.org. This is the Technical Documentation for the API.

Endpoint

Implementation Notes

  • All data is sent and received as JSON.
  • All timestamps 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

Parameters

  • For GET requests, optional parameters not specified as part of the path should be sent in the HTTP request string:
GET /orgs/WHO/sources/ICD-10-WHO/concepts?q=malaria
  • For all other HTTP verbs (e.g. POST, PUT, DELETE), parameters not specified as part of the path should be encoded as JSON with a Content-Type of 'application/x-www-form-urlencoded':
POST /user
{
    "name": "Johnny Doe",
    "email": "jdoe@me.com",
    "company": "My New Company",
    "location": "Eldoret, Kenya",
    "preferredLocale": "en,sw"
}

Resource Summary

The API exposes 12 resources that can be split into 4 categories (Note that comments have been postponed to a future release).

User Resources User-Generated Resources Terminology Resources Normalized Concept
Resources
User
Organization		 Collection
Tag
Star
Comment 		Source
Concept
Mapping		 Class
Datatype
Maptype

Definitions:

  • classes - Identifies a concept as a symptom, finding, procedure, drug, diagnosis, etc. OCL provides a normalized view of classes across concept sources.
  • collections - Versioned containers of concepts from one or more sources. These are used to organize existing concepts into useful groupings.
  • concepts - List concepts, terms, measures, and indicators across all sources
  • datatypes - Identifies the value associated with a concept as numeric, text, coded, percentage, etc. OCL provides a normalized view of datatypes across concept sources.
  • mappings - A mapping between 2 concepts of the same or different sources.
  • maptypes - Defines the types of relationships between concepts (e.g. "same as", "narrower than")
  • orgs - A group of one or more users that can own sources and collections.
  • sources - Versioned repositories of concepts, terms, measures, or indicators (e.g. LOINC v2.44, SNOMED CT). These are used to create or edit concepts. A source of type "reference" is also created for mappings to external dictionaries that are not stored in OCL (e.g. ICPC or RxNorm)
  • stars - Users may "star" concepts, collections, and sources to denote preference. Stars are either on or off, rather than, for example a 1 to 5 rating.
  • tags - Unstructured tags for sources, collections, and concepts
  • users - Individual authentication accounts on OCL

Postponed resources:

  • comments - Comments are used to annotate sources, collections, and concepts

A catalog of the available resources is available here:

  • catalog

Notes on Documentation

  • There are two generic forms of referring to concepts:
/user/:dictionaryType/:dictionary(/:dictionaryVersion)/concepts/:concept(/:conceptVersion)
/:ownerType/:owner/:dictionaryType/:dictionary(/:dictionaryVersion)/concepts/:concept(/:conceptVersion)
  • Where fields are defined as:
    • :ownerType - "users" or "orgs"
    • :owner - username or orgname
    • :dictionaryType - "sources" or "collections"
    • :dictionary - id of the source or collection
    • :dictionaryVersion (optional) - version number of the source or collection; if ommitted, the latest version is returned; cannot be used in conjunction with "conceptVersion"
    • :concept - id of the concept
    • :conceptVersion (optional) - version of a specific concept; cannot be used in conjunction with "dictionaryVersion"

Users and Organizations

  • users represent individual authentication accounts on OCL
  • orgs contain one or more users as members
  • Both users and orgs can own sources and collections
  • orgs cannot edit any content (e.g. concepts, mappings, etc.) directly since they are unable to login to OCL; instead, authenticated users with appropriate privileges may edit content on behalf of the organization that owns it.
  • Refer to the User page for administrative editing access to users
# users
GET /users                    # List all users
GET /users?q=:search          # Search users
GET /users/:user              # Get specific user
GET /users/:user/orgs         # List the specified user's organizations

# authenticated user
GET /user                     # Get currently authenticated user
GET /user/orgs                # Get authenticated user's orgs

# orgs
GET /orgs                     # List all organizations
GET /orgs?q=:search           # Search organizations
GET /orgs/:org                # Get specific organization
GET /orgs/:org/members        # List members of an organization
  • Update currently authenticated user
POST /user                    # Partial update of authenticated user
  • Editing orgs 
POST /orgs                    # Create new organization for the authenticated user
POST /orgs/:org               # Partial update of organization
PUT /orgs/:org                # Full update of organization
DELETE /orgs/:org             # Delete organization

Sources and Collections

  • sources are versioned repositories of concepts (e.g. LOINC v1) - these are the only means of creating new concepts
  • collections are versioned containers of concepts contained in one or more sources - these are how users organize concepts into useful lists
  • sources and collections are accessed through the users or organizations that own them
# sources
/users/:user/sources                    # List sources for the user
/users/:user/sources/:source            # Get specific source for the user
/orgs/:org/sources                      # List sources for the organization
/orgs/:org/sources/:source              # Get specific source for the organization

# collections
/users/:user/collections                # List collections for the user
/users/:user/collections/:collection    # Get specific collection for the user
/orgs/:org/collections                  # List collections for the organization
/orgs/:org/collections/:collection      # Get specific collection for the organization
  • Editing sources 
# Create
POST /users/:user/sources               # Create new source
POST /orgs/:org/sources                 # Create new source

# Partial update
POST /users/:user/sources/:source       # Partial update of specified source
POST /orgs/:org/sources/:source         # Partial update of specified source

# Full update
PUT /users/:user/sources/:source        # Full update of specified source
PUT /orgs/:org/sources/:source          # Full update of specified source

# Delete
DELETE /users/:user/sources/:source     # Delete specified source
DELETE /orgs/:org/sources/:source       # Delete specified source
  • Editing collections 
# Create
POST /users/:user/collections                 # Create new collection
POST /orgs/:org/collections                   # Create new collection

# Partial update
POST /users/:user/collections/:collection     # Partial update of specified collection
POST /orgs/:org/collections/:collection       # Partial update of specified collection

# Full update
PUT /users/:user/collections/:collection      # Full update of specified collection
PUT /orgs/:org/collections/:collection        # Full update of specified collection

# Delete
DELETE /users/:user/collections/:collection   # Delete specified collection
DELETE /orgs/:org/collections/:collection     # Delete specified collection

List Sources and Collections Across Users and Organizations

  • The /sources and /collections endpoints can be used to list or search sources and collections across all users and organizations
GET /sources               # List public sources across all users and organizations
GET /sources?q=icd         # Search public sources across all users and organizations
GET /collections           # List public collections across all users and organizations
GET /collections?q=icd     # Search public collections across all users and organizations

Versioning of Sources and Collections

  • Major new releases (esp. non-backwards compatible releases) are considered a new source or collection. The relationship between the 2 resources should be indicated in the metadata.
  • Minor releases should be backwards compatible.
  • Use the versions sub-resource to list the available versions of a source or collection
# List versions
GET /users/:user/sources/:source/versions
GET /orgs/:org/sources/:source/versions
GET /users/:user/collections/:collection/versions
GET /orgs/:org/collections/:collection/versions
  • The latest released versions of sources and collections are accessed using the "magic" latest version identifier.
  • Specific versions of sources and collections are accessed using the version number (e.g. 1.01)
# sources
GET /users/:user/sources/:source/latest             # Retreive metadata for the latest version
GET /users/:user/sources/:source/:version           # Retreive metadata for specified version
GET /orgs/:org/sources/:source/latest               # Retreive metadata for the latest version
GET /orgs/:org/sources/:source/:version             # Retreive metadata for specified version

# collections
GET /users/:user/collections/:collection/latest     # Retreive metadata for the latest version
GET /users/:user/collections/:collection/:version   # Retreive metadata for specified version
GET /orgs/:org/collections/:collection/latest       # Retreive metadata for the latest version
GET /orgs/:org/collections/:collection/:version     # Retreive metadata for specified version
  • Editing versions
# sources
POST /users/:user/sources/:source/versions              # Create a new version
PUT /users/:user/sources/:source/versions/:version      # Full update of specified version
DELETE /users/:user/sources/:source/versions/:version   # Delete version
POST /orgs/:org/sources/:source/versions                # Create a new version
PUT /orgs/:org/sources/:source/versions/:version        # Full update of specified version
DELETE /orgs/:org/sources/:source/versions/:version     # Delete version

# collections
POST /users/:user/collections/:collection/versions              # Create a new version
PUT /users/:user/collections/:collection/versions/:version      # Full update of specified version
DELETE /users/:user/collections/:collection/versions/:version   # Delete version
POST /orgs/:org/collections/:collection/versions                # Create a new version
PUT /orgs/:org/collections/:collection/versions/:version        # Full update of specified version
DELETE /orgs/:org/collections/:collection/versions/:version     # Delete version

Concepts

  • concepts are owned by sources and are referenced by several other resources (e.g. collections and mappings)
  • To retrieve the details of a concept, it must be accessed through the user or organization that owns it
# List concepts
GET /user/sources/:source/concepts						# Latest version of concepts
GET /user/sources/:source/:version/concepts				# Concept for specific version of source
GET /users/:user/sources/:source/concepts
GET /users/:user/sources/:source/:version/concepts
GET /orgs/:org/sources/:source/concepts
GET /orgs/:org/sources/:source/:version/concepts

# Search
GET /users/:user/sources/:source/concepts?q=malaria
GET /orgs/:org/sources/:source/concepts?q=malaria

# Get specific concept
GET /users/:user/sources/:source/concepts/:concept
GET /orgs/:org/sources/:source/concepts/:concept
  • Parameters
GET /users/:user/sources/:source/concepts?class=:class
GET /orgs/:org/sources/:source/concepts?dataytpe=:datatype
  • Editing concepts in sources 
# users
POST /users/:user/sources/:source/concepts/               # Create new concept
POST /users/:user/sources/:source/concepts/:concept       # Partial update
PUT /users/:user/sources/:source/concepts/:concept        # Full update
DELETE /users/:user/sources/:source/concepts/:concept     # Delete concept

# orgs
POST /orgs/:org/sources/:source/concepts/                 # Create new concept
POST /orgs/:org/sources/:source/concepts/:concept         # Partial update
PUT /orgs/:org/sources/:source/concepts/:concept          # Full update
DELETE /orgs/:org/sources/:source/concepts/:concept       # Delete concept

List Concepts Across Sources

  • The /concepts endpoint can be used to list or search concepts across all sources
GET /concepts                      # List sources across all users and organizations
GET /concepts?q=malaria            # Search sources across all users and organizations

# Parameters
GET /concepts?class=:class         # List concepts by class
GET /concepts?datatype=:datatype   # List concepts by datatype

Concepts in a Collection

  • List or search concepts in collections similar how they are retrieved from sources
  • Note that the reference url of the concepts are from their sources, not the collections 
# List
GET /users/:user/collections/:collection/concepts             # List concepts
GET /orgs/:org/collections/:collection/concepts               # List concepts

# Search
GET /users/:user/collections/:collection/concepts?q=:search   # Search concepts
GET /orgs/:org/collections/:collection/concepts?q=:search     # Search concepts
  • Adding concepts to collections 
POST /users/:user/collections/:collection/concepts/:concept
POST /users/johndoe/collections/my-collection/concepts/ciel:12345
  • Removing concepts from collections (e.g DELETE /users/johndoe/collections/my-collection/concepts/ciel:12345)
DELETE /users/:user/collections/:collection/concepts/:concept

Normalized Resources

  • classes, datatypes, and maptypes are normalized across sources, meaning that the equivalent Numeric data types in LOINC and SNOMED CT actually point to the same resource
  • Use the /classes, /datatypes, and /maptypes endpoints to list all available resources
# Class
GET /classes                       # List all classes
GET /classes?q=:search             # Search classes
GET /classes/:class                # Retrieve a specific class
GET /classes/:class/sources        # List sources in which class is a member

# Datatype
GET /datatypes                     # List all datatypes
GET /datatypes?q=:search           # Search datatypes
GET /datatypes/:datatype           # Retrieve a specific datatype
GET /datatypes/:datatype/sources   # List sources in which datatype is a member

# Maptype
GET /maptypes                      # List all maptypes
GET /maptypes?q=:search            # Search maptypes
GET /maptypes/:maptype             # Retrieve a specific maptype
GET /maptypes/:maptype/sources     # List sources in which maptype is a member
  • To list which classes, datatypes, and maptypes are available to a source
# User
GET /users/:user/sources/:source/classes
GET /users/:user/sources/:source/datatypes

# Organization
GET /orgs/:org/sources/:source/classes
GET /orgs/:org/sources/:source/datatypes
  • Editing classes, datatypes, and maptypes 
# Class
POST /classes                   # Create new class
POST /classes/:class            # Partial update of class
PUT /classes/:class             # Full update of class
DELETE /classes/:class          # Delete class

# Dataype
POST /datatypes                 # Create new class
POST /datatypes/:datatype       # Partial update of class
PUT /datatypes/:datatype        # Full update of class
DELETE /datatypes/:datatype     # Delete class

# Maptype
POST /maptypes                  # Create new class
POST /maptypes/:maptype         # Partial update of class
PUT /maptypes/:maptype          # Full update of class
DELETE /maptypes/:maptype       # Delete class
  • Adding or removing from sources - note that you cannot remove classes, datatypes or maptypes from sources if they are in use
# Class
POST /orgs/:org/sources/:source/classes/:class           # Add class to source
DELETE /orgs/:org/sources/:source/classes/:class         # Remove class from a source

# Datatype
POST /orgs/:org/sources/:source/datatypes/:datatype      # Add class to source
DELETE /orgs/:org/sources/:source/datatypes/:datatype    # Remove class from a source

# Maptype
POST /orgs/:org/sources/:source/maptypes/:maptype        # Add class to source
DELETE /orgs/:org/sources/:source/maptypes/:maptype      # Remove class from a source

Mappings

  • mappings define a relationship between two concepts in the same or different sources
  • The type of relationship is described by the maptype resource
# List all mappings
GET /mappings

# Retrieve mappings filtered by `maptype`
GET /mappings?maptye=:maptype

# Retrieve mappings FROM or TO a concept (e.g. GET /mappings?concept=snomed:12845003)
GET /mappings?concept=:concept

# Retrieve mappings originating FROM a concept (e.g. GET /mappings?conceptA=ciel:105949)
GET /mappings?conceptA=:conceptA

# Retrieve mappings pointing TO a concept (e.g. GET /mappings?concept=snomed:12845003)
GET /mappings?conceptB=:conceptB

# Retrieve mappings from a specified concept to a specified concept (e.g. GET /mappings?conceptA=ciel:105949&conceptB=snomed:12845003)
GET /mappings?conceptA=:conceptA&conceptB=:conceptB

# Retrieve mappings in any direction between 2 concepts (e.g. GET /mappings?concept=ciel:105949,snomed:12845003)
GET /mappings?concept=:concept1,:concept2

# Retrieve mapping based on UUID
GET /mappings/:mapping
  • Alternative modeling to consider for querying mappings by concept - use direction paramter to indicate "to", "from", "any" - need to determine how this would work if querying for 2 concepts
GET /mappings?concept=:concept&direction=:direction
  • Editing mappings 
POST /mappings                  # Create new mapping
POST /mappings/:mapping         # Partial update of mapping
DELETE /mappings/:mapping       # Delete mapping

Tags and Stars

  • Tags and Stars can be applied to collections, sources, and concepts 
GET /stars                  # Get all stars

# Get all stars for a user
GET /stars?user=:user
GET /users/:user/stars

# Filter based on resource type. Supported types are "concept", "source", and "collection"
GET /stars?resourceType=:resourceType

# Filter stars based on a single resource
GET /stars?resourceUri=:resourceUri 
GET /users/:user/sources/:source/concepts/:concept/stars
GET /users/:user/sources/:source/stars
GET /users/:user/collections/:collection/stars

# Get a single star
GET /stars?user=:user&resourceUri=:resourceUri

# Support Star UUID?
GET /stars/:star
  • Edit stars 
POST /stars                   # Create new star

# Delete using parameters?
DELETE /stars?user=:user&resourceUri=:resourceUri

# Support Star UUID?
DELETE /stars/:star           # Delete a star

Overview

Resources

Import / Export

Troubleshooting & Operations

Other

Clone this wiki locally