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.

We will be using Snow Owl's Core API to check its status. You can run the following command by clicking the "Copy" link on the right side and pasting it into a terminal.

curl http://localhost:8080/snowowl/info?pretty

And the response:

{
  "version": "<version>",
  "description": "You Know, for Terminologies",
  "repositories": {
    "items": [ {
      "id" : "snomed",
      "health" : "GREEN",
      "diagnosis" : "",
      "indices" : [ {
        "index" : "snomed-relationship",
        "status" : "GREEN"
      }, {
        "index" : "snomed-commit",
        "status" : "GREEN"
      }, ...
    } ]
  }
}

We can see the installed version along with available repositories, their overall health (eg. "snomed" with health "GREEN"), associated indices and status (eg. "snomed-relationship" with status "GREEN").

Repository indices store content for any number of code systems that share the same data structure and API, in the case of "snomed" the International Edition of SNOMED CT and its extensions.

Whenever we ask for repository 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)

Let's import an RF2 release in SNAPSHOT mode so that we can further explore the available SNOMED CT APIs! To do so, use the appropriate request from the as follows (the second SNOMEDCT in the request path represents the code system identifier):

Curl will display the entire interaction between it and the server, including many request and response headers. We are interested in these two (response) rows in particular:

The first one indicates that the file was uploaded successfully and a resource has been created to track import progress, while the second row indicates the location of this resource.

The process itself is asynchronous and its status can be checked by periodically sending a GET request to the location indicated by the response header:

The expected response while the import is running:

Upon completion, you should receive a different response which lists component identifiers visited during the import as well as any defects encountered in uploaded release files:

GET the ROOT concept:

And the response:

Search by ECL:

And the response:

Now that we have a code system, let's take a look at its content! We can list concepts using either the SNOMED CT API tailored to this tooling, or the FHIR API for a representation that is uniform across different kinds of code systems. For the sake of simplicity, we will use the former in this example.

To list all available concepts in a code system, use the following command (just as with importing, the second SNOMEDCT in the request path represents the code system identifier):

curl http://localhost:8080/snowowl/snomedct/SNOMEDCT/concepts?pretty

The expected response is:

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

The concept list is empty, indicating that we haven't imported anything into Snow Owl - yet.

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

curl http://localhost:8080/snowowl/codesystems?pretty

The response:

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

...it sure looks empty! This is expected, as Snow Owl does not contain any predefined code system metadata out of the box. We can create the first code system with the following request:

curl -X POST \
-H "Content-type: application/json" \
http://localhost:8080/snowowl/codesystems \
-d '{
  "id": "SNOMEDCT",
  "url": "http://snomed.info/sct/900000000000207008",
  "title": "SNOMED CT International Edition",
  "language": "en",
  "description": "SNOMED CT International Edition",
  "status": "active",
  "copyright": "(C) 2022 International Health Terminology Standards Development Organisation 2002-2022. All rights reserved.",
  "owner": "snowowl",
  "contact": "https://snomed.org",
  "oid": "2.16.840.1.113883.6.96",
  "toolingId": "snomed",
  "settings": {
    "moduleIds": [
      "900000000000207008",
      "900000000000012004"
    ],
    "locales": [
      "en-x-900000000000508004",
      "en-x-900000000000509007"
    ],
    "languages": [
      {
        "languageTag": "en",
        "languageRefSetIds": [
          "900000000000509007",
          "900000000000508004"
        ]
      },
      {
        "languageTag": "en-us",
        "languageRefSetIds": [
          "900000000000509007"
        ]
      },
      {
        "languageTag": "en-gb",
        "languageRefSetIds": [
          "900000000000508004"
        ]
      }
    ],
    "publisher": "SNOMED International",
    "namespace": "373872000",
    "maintainerType": "SNOMED_INTERNATIONAL"
  }
}'

The request body includes:

• The code system identifier "SNOMEDCT"

• Various pieces of metadata offering a human-readable title, ownership and contact information, code system status, URL and OID for identification, etc.

• The tooling identifier "snomed" that points to the repository that will store content

• Additional code system settings stored as key-value pairs

If everything goes well, the command will run without any errors (the server returns a "204 No Content" response). We can double-check that code system metadata has been registered correctly with the following request:

curl http://localhost:8080/snowowl/codesystems/SNOMEDCT?pretty

The expected response is:

{
  "id": "SNOMEDCT",
  "url": "http://snomed.info/sct/900000000000207008",
  "title": "SNOMED CT International Edition",
  "language": "en",
  ...
  "branchPath": "MAIN/SNOMEDCT",
  ...
}

In addition to the submitted values, you will find that additional administrative properties also appear in the output. One example is branchPath which specifies the working branch of the code system within the repository.