Now that we have our instance up and running, the next step is to understand how to communicate with it. Fortunately, Snow Owl provides very comprehensive and powerful APIs to interact with your instance.

REST API

Among the few things that can be done with the API are as follows:

• Check your instance health, status, and statistics

• Administer your instance data

• Perform CRUD (Create, Read, Update, and Delete) and search operations against your terminologies

• Execute advanced search operations such as paging, sorting, filtering, scripting, aggregations, and many others

Let’s start with a basic health check, which we can use to see how our instance is doing. We’ll be using curl to do this but you can use any tool that allows you to make HTTP/REST calls. Let’s assume that we are still on the same node where we started Snow Owl on and open another command shell window.

To check the instance status/health, we will be using the Admin API. You can run the command by clicking the "Copy" link on the right side and pasting it into a terminal.

curl http://localhost:8080/snowowl/admin/info

And the response:

{
  "version": "<version>",
  "description": "You Know, for Terminologies",
  "repositories": {
    "items": [
      {
        "id": "snomedStore",
        "health": "GREEN"
      }
    ]
  }
}

In the response, we can see the version of our instance along with the available repositories and their health status (eg. SNOMED CT with status GREEN).

Whenever we ask for the status, we either get GREEN, YELLOW, or RED and an optional diagnosis message.

• Green - everything is good (repository is fully functional)

• Yellow - some data or functionality is not available, or diagnostic operation is in progress (repository is partially functional)

• Red - diagnostic operation required in order to continue (repository is not functional)

Now that we have a SNOMED CT Code System, let's take a look at its content. We can query its content using either the SNOMED CT API or the FHIR API.

For sake of simplicity, let's search for the available concepts using the SNOMED CT API. For that we will need the branch we would like to query, but fortunately we already know the value from our previous call to the Code Systems API, it was MAIN. To list all available concepts in a SNOMED CT Code System, use the following command:

curl http://localhost:8080/snowowl/snomed-ct/v3/MAIN/concepts

And the response is:

{
  "items": [],
  "limit": 50,
  "total": 0
}

Which simply means we have no SNOMED CT concepts yet in our instance.

GET the ROOT concept:

curl 'http://localhost:8080/snowowl/snomed-ct/v3/MAIN/concepts/138875005'

And the response:

{
  "id": "138875005",
  "released": true,
  "active": true,
  "effectiveTime": "20020131",
  "moduleId": "900000000000207008",
  "iconId": "138875005",
  "definitionStatus": "PRIMITIVE",
  "subclassDefinitionStatus": "NON_DISJOINT_SUBCLASSES"
}

Search by ECL:

curl 'http://localhost:8080/snowowl/snomed-ct/v3/MAIN/concepts?active=true&ecl=%3C!138875005&limit=1'

And the response:

{
  "items": [
    {
      "id": "308916002",
      "released": true,
      "active": true,
      "effectiveTime": "20020131",
      "moduleId": "900000000000207008",
      "iconId": "138875005",
      "definitionStatus": "PRIMITIVE",
      "subclassDefinitionStatus": "NON_DISJOINT_SUBCLASSES"
    }
  ],
  "searchAfter": "AoE_BWVlYzI3Mjc0LTYyZTctNDg3NS05NmVlLThhNTk3OTcxOTJiNw==",
  "limit": 1,
  "total": 19
}

Now let's take a peek at our code systems:

curl http://localhost:8080/snowowl/admin/codesystems

And the response:

{
  "items": [
    {
      "oid": "2.16.840.1.113883.6.96",
      "name": "SNOMED CT",
      "shortName": "SNOMEDCT",
      "organizationLink": "http://www.snomed.org",
      "primaryLanguage": "ENG",
      "citation": "SNOMED CT contributes to the improvement of patient care by underpinning the development of Electronic Health Records that record clinical information in ways that enable meaning-based retrieval. This provides effective access to information required for decision support and consistent reporting and analysis. Patients benefit from the use of SNOMED CT because it improves the recording of EHR information and facilitates better communication, leading to improvements in the quality of care.",
      "branchPath": "MAIN",
      "iconPath": "icons/snomed.png",
      "terminologyId": "com.b2international.snowowl.terminology.snomed",
      "repositoryUuid": "snomedStore"
    }
  ]
}

Which means, we have a single Code System in Snow Owl, called SNOMED CT. It has been created by the SNOMED CT module by default on the first startup of your instance. A Code System lives in a repository and its working branchPath is currently associated with the default MAIN branch in the snomedStore repository.

Now let's import an official SNOMED CT RF2 SNAPSHOT distribution archive so that we can further explore the available SNOMED CT APIs.

To import an RF2 archive you must first create an import configuration using the as follows:

And the response:

The import configuration specifies the type of the RF2 release (in this case SNAPSHOT) and the target branchPath where the content should imported. The response returns an empty body along with a Location header with a URL pointing to the created import configuration. You can extract the last part of the URL to get the import configuration ID which can be used to retrieve the configuration and to upload the actual archive and start the import.

The import will start automatically when you upload the archive to the /imports/:id/archive endpoint:

The import process is asynchronous and its status can be checked by sending a GET request to the /imports/:id endpoint with the extracted import identifier as follows:

And the response:

The status field describes the current state of the import, while the startDate and completionDate fields specify start and completion timestamps.