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.

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.

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/snomed-ct/v3/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/snomed-ct/v3/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/snomed-ct/v3/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 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 /snomed-ct/v3/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 /snomed-ct/v3/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 /snomed-ct/v3/MAIN/a^/concepts/138875005

Response

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

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

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 /snomed-ct/v3/branches

Available resources and services

• Branching

• Compare

• Commits

• Concepts

• Descriptions

• Relationships

• RefSets

• Classification

• Import

• Export