All pages
Powered by GitBook
1 of 18

API

This describes the resources that make up the official Snow Owl® RESTful API.

Media Types

Custom media types are used in the API to let consumers choose the format of the data they wish to receive. This is done by adding one of the following types to the Accept header when you make a request. Media types are specific to resources, allowing them to change independently and support formats that other resources don’t.

The most basic media types the API supports are:

  1. application/json;charset=UTF-8 (default)

  2. text/plain;charset=UTF-8

  3. text/csv;charset=UTF-8

  4. application/octet-stream (for file downloads)

  5. multipart/form-data (for file uploads)

The generic JSON media type (application/json) is available as well, but we encourage you to explicitly set the accepted content type before sending your request.

Schema

All data is sent and received as JSON. Blank fields are omitted instead of being included as null.

All non-effective time timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Effective Time values are sent and received in short format:

yyyyMMdd

Hypermedia

All POST requests return Location headers pointing to the created resource instead of including either the identifier or the entire created resource in the response body. These are meant to provide explicit URLs so that proper API clients don’t need to construct URLs on their own. It is highly recommended that API clients use these. Doing so will make future upgrades of the API easier for developers. All URLs are expected to be proper RFC 6570 URI templates.

Example Location Header:

http://example.com/snowowl/snomedct/MAIN/concepts/123456789

Pagination

Requests that return multiple items will be paginated to 50 items by default. You can request further pages with the searchAfter query parameter.

Link/Resource expansion

Where applicable, the expand query parameter will include nested objects in the response, to avoid having to issue multiple requests to the server.

Expanded properties should be followed by parentheses and separated by commas; any options for the expanded property should be given within the parentheses, including properties to expand. Typical values for parameters are given in the "Implementation Notes" section of each endpoint.

GET /snowowl/snomedct/MAIN/concepts?offset=0&limit=50&expand=fsn(),descriptions()

Response:

{
  "items": [
    {
      "id": "100005",
      "released": true,
      ...
      "fsn": {
        "id": "2709997016",
        "term": "SNOMED RT Concept (special concept)",
        ...
      },
      "descriptions": {
        "items": [
          {
            "id": "208187016",
            "released": true,
            ...
          },
        ],
        "offset": 0,
        "limit": 5,
        "total": 5
      }
    },
    ...
  ],
  "offset": 0,
  "limit": 50,
  "total": 421657
}

Client Errors

There are three possible types of client errors on API calls that receive request bodies:

Invalid JSON

Status: 400 Bad Request
{
  "status" : "400",
  "message" : "Invalid JSON representation",
  "developerMessage" : "detailed information about the error for developers"
}

Valid JSON but invalid representation

Status: 400 Bad Request 
{
  "status" : "400",
  "message" : "2 Validation errors",
  "developerMessage" : "Input representation syntax or validation errors. Check input values.",
  "violations" : ["violation_message_1", "violation_message_2"]
}

Conflicts

Status: 409 Conflict 
{
  "status" : "409",
  "message" : "Cannot merge source 'branch1' into target 'MAIN'."
}

Server Errors

In certain circumstances, Snow Owl might fail to process and respond to a request and responds with a 500 Internal Server Error.

Status: 500 Internal Server Error 
{
  "status" : "500",
  "message" : "Something went wrong during the processing of your request.",
  "developerMessage" : "detailed information about the error for developers"
}

To troubleshoot these please examine the log files at {SERVER_HOME}/serviceability/logs/log.log and/or raise an issue on GitHub.

Path expressions

Snow Owl is a revision-based terminology server, where each stored terminology data (concepts, descriptions, etc.) is stored in multiple revisions, across multiple branches. When requesting content from the terminology server, clients are able to specify a path value or expression to select the content they'd like to access and receive. For example, Snow Owl supports importing SNOMED CT content from different sources, allowing eg. multiple national Extensions to co-exist with the base International Edition provided by SNOMED International. Versioned editions can be consulted when non-current representations of concepts need to be accessed. Concept authoring and review can also be done in isolation. Both Java and REST API endpoints require a path parameter to select the content (or substrate) the user wishes to work with.

The following formats are accepted:

Absolute branch path

Absolute branch path parameters start with MAIN and point to a branch in the backing terminology repository. In the following example, all concepts are considered to be part of the substrate that are on branch MAIN/2021-01-31/SNOMEDCT-UK-CL or any ancestor (ie. MAIN or MAIN/2021-01-31), unless they have been modified:

GET /snomedct/MAIN/2021-01-31/SNOMEDCT-UK-CL/concepts
{
  "items": [
    {
      "id": "100000000",
      "released": true,
      "active": false,
      "effectiveTime": "20090731",
[...]

Relative branch path

Relative branch paths start with a short name identifying a SNOMED CT code system, and are relative to the code system's working branch. For example, if the working branch of code system SNOMEDCT-UK-CL is configured to MAIN/2021-01-31/SNOMEDCT-UK-CL, concepts visible on authoring task #100 can be retrieved using the following request:

GET /snomedct/SNOMEDCT-UK-CL/100/concepts

An alternative request that uses an absolute path would be the following:

GET /snomedct/MAIN/2021-01-31/SNOMEDCT-UK-CL/100/concepts

An important difference is that the relative path parameter tracks the working branch specified in the code system's settings, so requests using relative paths do not need to be adjusted when a code system is upgraded to a more recent International Edition.

Path range

The substrate represented by a path range consists of concepts that were created or modified between a starting and ending point, each identified by an absolute branch path (relative paths are not supported). The format of a path range is fromPath...toPath.

To retrieve concepts authored or edited following version 2020-08-05 of code system SNOMEDCT-UK-CL, the following path expression should be used:

GET /snomedct/MAIN/2019-07-31/SNOMEDCT-UK-CL/2020-08-05...MAIN/2021-01-31/SNOMEDCT-UK-CL/concepts

The result set includes the ones appearing or changing between versions 2019-07-31 and 2021-01-31 of the International Edition; if this is not desired, additional constraints can be added to exclude them.

Path with timestamp

To refer to a branch state at a specific point in time, use the path@timestamp format. The timestamp is an integer value expressing the number of milliseconds since the UNIX epoch, 1970-01-01 00:00:00 UTC, and corresponds to "wall clock" time, not component effective time. As an example, if the SNOMED CT International version 2021-07-31 is imported on 2021-09-01 13:50:00 UTC, the following request to retrieve concepts will not include any new or changed concepts appearing in this release:

GET /snomedct/MAIN@1630504199999/concepts

Both absolute and relative paths are supported in the path part of the expression.

Branch base point

Concept requests using a branch base point reflect the state of the branch at its beginning, before any changes on it were made. The format of a base path is path^ (only absolute paths are supported):

GET /snomedct/MAIN/2019-07-31/SNOMEDCT-UK-CL/101^/concepts

Returned concepts include all additions and modifications made on SNOMEDCT-UK-CL's working branch, up to point where task #101 starts; neither changes committed to the working branch after task #101, nor changes on task #101 itself are reflected in the result set.

Core API

Detailed API documentation is coming soon! Until then we recommend to check out the official Swagger documentation available on your Snow Owl instance at /snowowl/admin.

SNOMED CT API

This describes the resources that make up the official Snow Owl® SNOMED CT Terminology API.

Swagger documentation available on your Snow Owl instance at /snowowl/snomedct.

Current Version

SNOMED CT API endpoints currently have version v3. You have to explicitly set the version of the API via path parameter. For example:

GET /snomedct/branches

Available resources and services

Branching

Snow Owl provides branching support for terminology repositories. In each repository there is an always existing and UP_TO_DATE branch called MAIN. The MAIN branch represents the latest working version of your terminology (similar to a master branch on GitHub).

You can create your own branches and create/edit/delete components and other resources on them. Branches are identified with their full path, which should always start with MAIN. For example the branch MAIN/a/b/c/d represents a branch under the parent MAIN/a/b/c with name d.

Later you can decide to either delete the branch or merge the branch back to its parent. To properly merge a branch back into its parent, sometimes it is required to rebase (synchronize) it first with its parent to get the latest changes. This can be decided via the state attribute of the branch, which represents the current state compared to its parent state.

Branch states

There are five different branch states available:

  1. UP_TO_DATE - the branch is up-to-date with its parent there are no changes neither on the branch or on its parent

  2. FORWARD - the branch has at least one commit while the parent is still unchanged. Merging a branch requires this state, otherwise it will return a HTTP 409 Conflict.

  3. BEHIND - the parent of the branch has at least one commit while the branch is still unchanged. The branch can be safely rebased with its parent.

  4. DIVERGED - both parent and branch have at least one commit. The branch must be rebased first before it can be safely merged back to its parent.

  5. STALE - the branch is no longer in relation with its former parent, and should be deleted.

Snow Owl supports merging of unrelated (STALE) branches. So branch MAIN/a can be merged into MAIN/b, there does not have to be a direct parent-child relationship between the two branches.

Basics

Get a branch

GET /branches/:path

Response

Status: 200 OK
{
  "name": "MAIN",
  "baseTimestamp": 1431957421204,
  "headTimestamp": 1431957421204,
  "deleted": false,
  "path": "MAIN",
  "state": "UP_TO_DATE"
}

Get all branches

GET /branches

Response

Status: 200 OK
{
  "items": [
    {
      "name": "MAIN",
      "baseTimestamp": 1431957421204,
      "headTimestamp": 1431957421204,
      "deleted": false,
      "path": "MAIN",
      "state": "UP_TO_DATE"
    }
  ]
}

Create a branch

POST /branches

Input

{
  "parent" : "MAIN",
  "name" : "branchName",
  "metadata": {}
}

Response

Status: 201 Created
Location: http://localhost:8080/snowowl/snomedct/branches/MAIN/branchName

Delete a branch

DELETE /branches/:path

Response

Status: 204 No content

Merging

Perform a merge

POST /merges

Input

{
  "source" : "MAIN/branchName",
  "target" : "MAIN"
}

Response

Status: 202 Accepted
Location: http://localhost:8080/snowowl/snomedct/merges/2f4d3b5b-3020-4e8e-b046-b8266967d7dc

Perform a rebase

POST /merges

Input

{
  "source" : "MAIN",
  "target" : "MAIN/branchName"
}

Response

Status: 202 Accepted
Location: http://localhost:8080/snowowl/snomedct/merges/c82c443d-f3f4-4409-9cdb-a744da336936

Monitor progress of a merge or rebase

GET /merges/c82c443d-f3f4-4409-9cdb-a744da336936

Response

{
  "id": "c82c443d-f3f4-4409-9cdb-a744da336936",
  "source": "MAIN",
  "target": "MAIN/branchName",
  "status": "COMPLETED",
  "scheduledDate": "2016-02-29T13:52:45Z",
  "startDate": "2016-02-29T13:52:45Z",
  "endDate": "2016-02-29T13:53:06Z"
}

Remove merge or rebase queue item

DELETE /merges/c82c443d-f3f4-4409-9cdb-a744da336936

Response

Status: 204 No content

Compare

Compare API

Comparison for current terminology changes committed to a source or target branch can be conducted by creating a compare resource.

A review identifier can be added to merge requests as an optional property. If the source or target branch state is different from the values captured when creating the review, the merge/rebase attempt will be rejected. This can happen, for example, when additional commits are added to the source or the target branch while a review is in progress; the review resource state becomes STALE in such cases.

Reviews and concept change sets have a limited lifetime. CURRENT reviews are kept for 15 minutes, while review objects in any other states are valid for 5 minutes by default. The values can be changed in the server's configuration file.

Compare two branches

POST /compare 
{
  "baseBranch": "MAIN",
  "compareBranch": "MAIN/a",
  "limit": 100
}

Response

Status: 200 OK
{
  "baseBranch": "MAIN",
  "compareBranch": "MAIN/a",
  "compareHeadTimestamp": 1567282434400,
  "newComponents": [],
  "changedComponents": ["138875005"],
  "deletedComponents": [],
  "totalNew": 0,
  "totalChanged": 1,
  "totalDeleted": 0
}

Read component state from comparison

Terminology components (and in fact any content) can be read from any point in time by using the special path expression: {branch}@{timestamp}. To get the state of a SNOMED CT Concept from the previous comparison on the compareBranch at the returned compareHeadTimestamp, you can use the following request:

Request

GET /snomedct/MAIN@1567282434400/concepts/138875005

Response

Status: 200 OK
{
  "id": "138875005",
  ...
}

To get the state of the same SNOMED CT Concept but on the base branch, you can use the following request:

Request

GET /snomedct/MAIN/concepts/138875005

Response

Status: 200 OK
{
  "id": "138875005",
  ...
}

Additionally, if required to compute what's changed on the component since the creation of the task, it is possible to get back the base version of the changed component by using another special path expression: {branch}^.

Request

GET /snomedct/MAIN/a^/concepts/138875005

Response

Status: 200 OK
{
  "id": "138875005",
  ...
}

These characters are not URL safe characters, thus they must be encoded before sending the HTTP request.

Commits

Loading...

Descriptions

Coming soon!

Relationships

Coming soon!

Reference Sets

Two categories make up Snow Owl's Reference Set API:

  1. Reference Sets category to get, search, create and modify reference sets

  2. Reference Set Members category to get, search, create and modify reference set members

Basic operations like create, update, delete are supported for both category.

Actions API

On top of the basic operations, reference sets and members support actions. Actions have an action property to specify which action to execute, the rest of the JSON properties will be used as body for the Action.

Supported reference set actions are:

  1. sync - synchronize all members of a query type reference set by executing their query and comparing the results with the current members of their referenced target reference set

Supported reference set member actions are:

  1. create - create a reference set member (uses the same body as POST /members)

  2. update - update a reference set member (uses the same body as PUT /members)

  3. delete - delete a reference set member

  4. sync - synchronize a single member by executing the query and comparing the results with the current members of the referenced target reference set

For example the following will sync a query type reference set member's referenced component with the result of the reevaluated member's ESCG query

POST /members/:id/actions
{
  "commitComment": "Sync member's target reference set",
  "action": "sync"
}

Bulk API

Members list of a single reference set can be modified by using the following bulk-like update endpoint:

PUT /:path/refsets/:id/members

Input

{
  "commitComment": "Updating members of my simple type reference set",
  "requests": [
  	{
  	  "action": "create|update|delete|sync",
  	  "action-specific-props": ...
  	}
  ]
}

The request body should contain the commitComment property and a request array. The request array must contain actions (see Actions API) that are enabled for the given set of reference set members. Member create actions can omit the referenceSetId parameter, those will use the one defined as path parameter in the URL. For example by using this endpoint you can create, update and delete members of a reference set at once in one single commit.

Classification

Importing RF2

Exporting RF2

Loading...

FHIR API

FHIR API

Fast Healthcare Interoperability Resources (FHIR) specifies resources, operations, coded data types and terminologies that are used for representing and communicating coded, structured data in the FHIR core specification within its Terminology Module.

Snow Owl's pluggable and extensible architecture allows modular development of the FHIR API both in terms of the supported functionality as well as the exposed terminologies. Additionally, Snow Owl's revision-based model allows the concurrent management of multiple versions.

Resources

The Snow Owl terminology server's FHIR API release includes support for the following resources:

Versions

Versions in Snow Owl are represented as individual FHIR Resources when accessed via the FHIR API endpoints. If there are no versions present for a given resource, only the latest development version is returned as available FHIR Resource. When accessing a terminology resource via the FHIR API, but without specifying an exact version tag, then the system will always assume and return the latest development version, including not yet published changes. It is recommended to always query a specific version of any terminology content to get consistent results, especially when the same terminology server instance is being used for both authoring and distribution.

Search

Resource representations can be filtered by the following supported official FHIR payload filters:

  • _summary - to return a predefined set of properties and their values

  • _elements - to return only the mandatory and the specified list of properties and nothing else

The supported search parameters:

  • _id - to filter FHIR resources by their logical identifier

  • name - to filter FHIR resources by their name (which in Snow Owl equals to the logical identifier)

  • title - to filter FHIR resources by their title property lexically (Snow Owl by default uses exact, phrase and prefix matching during its lexical search activities)

  • url - to filter FHIR resources by their assigned url value

  • system - to filter FHIR resources by their assigned system value (which in Snow Owl always matches the url value)

  • version - to filter FHIR resource by their version property value

  • _lastUpdated - exposed but not supported yet

Sorting and paging

Sorting supported via standard FHIR sort parameters, while paging is supported with a new after parameter (using count as page size). Offset + count based traditional paging is not supported.

URIs

Globally unique logical URIs that represent a terminology resource. For code systems these are:

Code system
URI

SNOMED CT

http://snomed.info/sct

LCS

Defined when the resource was created

Value Set

Defined when the resource was created

Concept Map

Defined when the resource was created

ATC

http://www.whocc.no/atc

ICD-10

http://hl7.org/fhir/sid/icd-10

LOINC

http://loinc.org

SNOMED CT

For SNOMED CT, Snow Owl's FHIR implementation follows the SNOMED CT URI Standard.

ICD-10

For ICD-10, Snow Owl's FHIR implementation follows the HL7 FHIR Specification.

Local Code System

Snow Owl's Local Code Systems (LCS) identified by the URI that is based on the Organization Link property stored within Snow Owl's Terminology Registry and the Short Name of the LCS e.g.: https://b2i.sg/MyLocalCodeSystem.

IDs

The logical id field of each resource is assigned by Snow Owl and is unique within it. Once it has been assigned, the id never changes. For this logical identifier, Snow Owl follows the pattern:

resourceId[/version]

For example to identify a particular SNOMED CT Edition with its version 2021-03-01:

SNOMEDCT-US/2021-03-01

For example to identify a particular LOINC code system with the version tag v2.64:

 LOINC/v2.64

REST API

Currently only JSON format is supported with UTF-8 encoding and content type of Content-Type = application/fhir+json;charset=utf-8. In case of any errors during the processing the API responds with an OperationOutCome within the response body using one of the HTTP status codes:

HTTP Status
Reason

200

OK

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Error

Snow Owl's extension API

Snow Owl exposes a comprehensive REST API to support areas such as:

  • Syndication - content provisioning between servers or between the Snow Owl Authoring platform and servers

  • Administration (repository and revision control management)

  • Auditing

  • SNOMED CT specific browsing and authoring API

CodeSystem

Code Systems maintained within Snow Owl are exposed (read-only) via the endpoints /CodeSystem and /CodeSystem/{codeSystemId}. Supported concept properties are handled and returned if requested. The currently exposed code systems are:

Snow Owl OSS:

  • SNOMED CT

Snow Owl:

  • ATC

  • ICD-10 (and extensions)

  • LOINC

  • OPCS

  • Local Code Systems

  • Any other terminology

SNOMED CT

All standard and default SNOMED CT properties are supported, including the relationship type and concrete value properties. In addition to the FHIR SNOMED CT properties, Snow Owl can return the effective time property, with the URI http://snomed.info/field/Concept.effectiveTime.

Operations

$lookup

Both GET as well as POST HTTP methods are supported. Concepts are queried based on code, version, system or Coding. Designations are included as part of the response as well as supported concept properties when requested. No date parameter is supported.

Example for looking up properties (inactive and method) of the latest version of a SNOMED CT procedure by method code:

 /CodeSystem/$lookup?system=http://snomed.info/sct&code=128927009&_format=json&property=inactive&property=http://snomed.info/id/260686004

For SNOMED CT, all common and SNOMED CT properties are supported, including all active relationship types.

$validate-code

Both GET as well as POST HTTP methods are supported for all exposed terminologies. Example for validating a SNOMED CT code:

/CodeSystem/SNOMEDCT/2021-07-31/$validate-code?code=128927009

$subsumes

Both GET as well as POST HTTP methods are supported. Subsumption testing is supported for all terminologies, including SNOMED CT.

Example for SNOMED CT (version 2021-07-31):

/CodeSystem/$subsumes?codeA=409822003&codeB=264395009&system=http://snomed.info/sct/900000000000207008/version/20210731

ValueSet

ValueSet API

The endpoints /ValueSet and /ValueSet/{valueSetId} and corresponding operations expose all Value Set resources stored (or implict Value Sets if the corresponding Value Set plug-in supports it) in the server. CUD operations are not supported.

$expand

All value sets accessible via the /ValueSet endpoints can be expanded.

For SNOMED CT URIs, implicit value sets are supported:

  • ?fhir_vs - all Concept IDs in the edition/version. If the base URI is http://snomed.info/sct, this means all possible SNOMED CT concepts

  • ?fhir_vs=isa/[sctid] - all concept IDs that are subsumed by the specified Concept.

  • ?fhir_vs=refset - all concept ids that correspond to real references sets defined in the specified SNOMED CT edition

  • ?fhir_vs=refset/[sctid] - all concept IDs in the specified reference set

The following in-parameters are supported:

  • activeOnly - to return only active codes in the response

  • filter - to filter the results lexically

  • displayLanguage - to select the language for the returned display values

  • includeDesignations - whether to include all designations or not in the returned response

  • count - to select the number of codes to be returned in the expansion

  • after - to select codes to be returned after this last page value (cursor)

$validate-code

Codes can be validated against a given Value Set specified by the value set's logical id or canonical URL. In terms of Snow Owl terminology components, codes are validated against:

  • SNOMED CT Simple Type Reference Sets with Concepts as referenced components.

  • SNOMED CT Query Type Reference Sets with ECL expressions (each member is a Value Set)

  • Snow Owl's generic Value Sets

Validation performs the following checks:

  • The existence of the given Value Set (error if not found)

  • The existence of the reference in the existing Value Set to the given code (error if not found)

  • The existence of the given code in the system (error if not found)

  • Potential version mismatch (_error if the reference points to a version that is different to the code's version)

  • The status of the given code and reference (warning if code is inactive while reference is active)

Loading...