SNOMED International's MLDS provides a limited number of APIs to support integration with other systems.

For further information on the REST APIs to get access to releases, please go to the MLDS Release Packages API page.

Schema

All access to the API is over HTTPS to the [mlds.ihtsdotools.org](http://mlds.ihtsdotools.org) domain. All data is sent and received as JSON.

$ curl -i 'https://mlds.ihtsdotools.org/api/affiliates/check?member=IHTSDO&match=spectra' HTTP/1.1 200 OK Content-Type: application/json Transfer-Encoding: chunked Date: Tue, 27 Oct 2015 19:46:30 GMT 

{"matched":true}

Client errors

Client errors on API calls will typically result in a 400 Bad Request response.

HTTP/1.1 400 Bad Request Content-Type: application/json Transfer-Encoding: chunked Date: Tue, 27 Oct 2015 19:54:17 GMT
{
"error": "Bad Request",
"status": 400,
"message": "Unknown member: 'xz'. Valid options: AU BE BN CA CL CZ DK EE ES GB HK IHTSDO IL IN IS LT MT MY NL NZ PL PT SE SG SI SK US UY "
}

Error responses can be detected by a status code of 4xx or 5xx. The message value is an optional human description of the problem.

Authentication

The public APIs do not require authentication to be supplied.

HTTP Methods

Where possible the API supports appropriate HTTP Methods/Verbs for each resource.

Check that an affiliate is in good standing with IHTSDO.

Where possible the affilateId with confirming matching data from the application can be used, otherwise a single match from all affiliates of a member can be used. [code] GET /affiliates/check?member=:memberKey&match=:keyword[&affilateId=:affiliateId] [/code]

The check API requires a unique match in the Affiliates database. Affiliates are filtered by the member, optionally by affiliate id, and a keyword text match against the identifying fields of the affiliate.

Once a single affiliate has been identified the affiliate's application must have been approved for the specified member and for the affiliate's account to be considered in good standing.

If successful then the API will return with a matched: **true**.

If there is no match then the API will return with matched: **false**.

No additional information is provided to diagnose a failed match.

A successful match against a Swedish affiliate based on a match against the [abc@test.com](mailto:abc@test.com) email address. The affiliate was uniquely identified and the account was in good standing.

An unsuccessful match against an IHTSDO affiliate based a match against the keyword hospital. No affiliate was uniquely identified as many affiliates contained hospital in the searched fields.

A successful match that limited the search to a single specified affiliate. The 'hospital' keyword matched, unlike before, however, by limiting the search to a single affiliate the result was unique.

The match value contains user supplied data and as result may need to be escaped using standard URL rules. For example, matching the email address [me+work@email.com](mailto:me+work@email.com) would require escaping the + character as %2B when using curl or else the match request would fail.

Working with the SNOMED CT community, SNOMED International produced the following syndication standard, which has now been implemented in MLDS. The feed can be viewed here: https://mlds.ihtsdotools.org/api/feed

Terminology Server Syndication Standard

As part of a strategy to move towards wider adoption of healthcare terminology servers which implement the HL7 FHIR Terminology Services, a more effective way of distributing terminology would be from server to server through a syndication feed.

Based on existing work implemented by the Australian Digital Health Agency, this feed extends the Atom Syndication Standard. It is not specific to SNOMED CT and can be used for any relevant healthcare standard,

The additions here are from SNOMED International and are in the sct namespace, http://snomed.info/syndication/sct-extension/1.0.0, for distributing SNOMED CT content.

SNOMED CT Specific extensions

A live feed is now available from SNOMED International - Members Distribution and Licensing Service

Example feed can be seen in this repo - feed-example.xml.

The extensions to the specification are as follows:

<sct:packageDependency>
     <sct:editionDependency></sct:editionDependency>
     <sct:derivativeDependency></sct:derivativeDependency>
</sct:packageDependency>

These are SNOMED CT specific extensions to specify any package dependency for a given release package that are not included in the package itself. Dependencies can be on editions or other derivatives.

by definition include all their dependencies and therefore do not have a sct:packageDependency element.

always depend on other packages' content not included in the extension package and therefore always have a sct:packageDependency element.

and can therefore be distinguished by the absence or presence of a sct:packageDependency element.

Within a sct:packageDependency element

• sct:editionDependency states any necessary edition dependency and version using the SNOMED CT URI standard, e.g. http://snomed.info/sct/900000000000207008/version/20220731. Where a package is transitively dependent on multiple editions, only the direct non-transitive dependencies should be stated. Downloading packages would complete when there are no further dependencies.

• sct:derivativeDependency states any necessary derivative dependency, as they are often published outside of SNOMED CT editions. Similarly, this should also follow the SNOMED CT URI standard for module and version

While all types of entries can be put into one feed, it is also possible to host these entries in separate feeds. For examples

• an editions feed - edition packages of available SNOMED CT Editions/Extensions

• an extensions feed - extension packages of available SNOMED CT Extensions

• a derivatives feed - extension packages of available SNOMED CT Derivatives

Given that most implementers prefer a ready to use package to parts and assembly instructions, most implementers will be interested in edition packages rather than extension packages.

Providing a feed containing only edition packages without extension packages would be the least confusing entry point for most implementers with the least learning and decision making required.

Additional feeds for extension packages and derivatives would be useful for other implementations and are still worth providing.

A complete feed that is the union of these three feeds can also be potentially provided.

The major distinction between extensions and derivatives is that extensions add/modify core components, where derivatives are limited to reference sets providing non-core "bolt on" content.

For editions, most implementers want a ready to use package rather than parts and assembly instructions. Assembling an edition from an extension package and a base edition is not a trivial exercise, requiring content to be combined and a snapshot calculated based on the .

For this reason edition packaging is preferred as the primary distribution method extensions. Extensions may also be provided in extension packaging, however if only one is made availabe edition packaging is preferred.

The rationale for this recommendation is that

• implementers desiring an extension package are in the minority and more capable of disassembiling an edition package if necessary

• the majority of implementers would prefer a ready to use edition package, and the task of assembling that from an extension and base edition package and calculating a snapshot based on the is burdensome.

Derivatives are designed to bolt on to an edition, and as such are either "pre-mixed" into an edition package or provided as an extension package.

When provided by themselves, they make most sense provided as an extension package so they can be "bolted onto" a number of different compatible editions. Therefore the preferred packaging of a derivative is an extension package.

Note that this preference does not preclude prepackaging one or more derivatives in edition packages where useful.

Extensions, as opposed to derivatives, add/modify core components - concepts, descriptions and axioms/relationships. These changes affect the Snapshot state of components, as well as potenitally affecting classification and Necessary Normal Form calculation (for example non-leaf concept addition).

An Extension (adding/modifying core components) published as an extension package should only be a Delta or a Full . Such a package can be applied to a referenced base edition, and then a Snapshot calculated using the . Because an Extension affects the Snapshot state in this way, potentially requiring reclassification and Necessary Normal Form recalculation, a Snapshot extension package of an Extension cannot be simply appended to a base edition's Snapshot. For this reason, the Snapshot Release Type for extension packages of SNOMED CT Extensions should not be used.

In the simpler Derivative case (map, refset, even language translation with additional descriptions) a Snapshot extension package being simply appended to a Snapshot base edition is safe and simple because the derivative simply adds new components and does not affect the state of existing components.

The Snapshot Release Type for an edition package does not have these issues as the base edition content is included in the resolved Snapshot Release Type of the package.

To aid human readability and distinguish between packages, the following naming conventions should be applied.

1. Edition packages

   1. Should contain the word edition

   2. Should NOT contain the word extension

2. Extension packages

For example, titles following these conventions are

• SNOMED CT-International Edition 2023-04-30 (RF2 SNAPSHOT)

• SNOMED CT-International Spanish Extension 2023-10-31 (RF2 FULL)

Each feed entry should always have one link rel="alternate" link. This will generally be the SNOMED CT package to download.

There can also be one or more link rel="related" entries for any related files, including Release Notes or other relevant files.

Each link will have the following attributes:

• type - the type of file being downloaded, e.g. type="application/zip" or type="application/pdf"

• href - the URL link to download the file

• length

In each feed entry, the category will indicate the type of RF2 package. The expected types are as follows:

• SCT_RF2_ALL: Containing the Snapshot and Full RF2 release files (and potentially the Dela Rf2 files but this is not mandatory)

• SCT_RF2_FULL: Containing only Full RF2 release files

• SCT_RF2_SNAPSHOT: Containing only Snapshot RF2 release files

• SCT_RF2_DELTA: Containing only Delta RF2 release files

Most available RF2 packages will contain all the necessary release files and will, therefore, have a feed entry item as follows:

The standard does not mandate any authentication, and this is left to the implementer of the Atom feed provider to implement whatever is needed, depending on any terminology product license requirements.

Syndication of terminologies has a number of use cases. A few examples are:

Automatic distribution of content products by their owners:

• International content products

• National content products

• Regional content products

Automatic import of selected products and dependencies as updates become available:

• Automatic update of existing terminology server instances

  • Browser server containing both published content and daily builds

• Automatic provision of new terminology server instances

  • Autoscaling

Each member organization can make Release Packages available to their approved affiliates for downloading. A Release Package has a current version and past versions. A Release version can contain multiple files that can be individually downloaded by an affiliate.

Release files are not stored in MLDS and instead a URL is provided where the file can be download from on demand. Files are typically stored on the Amazon s3 service. The URL to directly access the release file is not made available to affiliate users, who instead use a MLDS based URL that in turn download the file from the original location.

Client errors

Client errors on API calls will typically result in a 400 Bad Request response.

[HTTP/1.1 400 Bad Request Content-Type: application/json Transfer-Encoding: chunked Date: Tue, 27 Oct 2015 19:54:17 GMT
{"error":"Bad Request","status":400,"message":"Unknown member: 'xz'. Valid options: AU BE BN CA CL CZ DK EE ES GB HK IHTSDO IL IN IS LT MT MY NL NZ PL PT SE SG SI SK US UY "}

Error responses can be detected by a status code of 4xx or 5xx. The message value is an optional human description of the problem.

Authentication

The public APIs do not require authentication to be supplied.

Basic Authentication

The APIs that do require authentication support Basic Authentication using MLDS credentials.

Ensure that all communication uses https to ensure the credentials aren't revealed.

Where possible, the API supports appropriate HTTP Methods/Verbs for each resource.

List all release packages. [code] $ curl -i 'https://mlds.ihtsdotools.org/api/releasePackages' [/code]

Add a new release file to a Release Version.

Note that an affiliate download URL is used by affiliates to download the content via MLDS. [/code]

To publish a Release Version online the Release Version's online flag should be set to true. To take the Release Version offline the online flag should be set to false.

A license document can be associated with a Release Package. [code] POST /api/releasePackages/:releasePackageId/license [/code]

The request should be a `multipart\form-data' post to the server.

The content associated with a Release File can be downloaded using the value of the `clientDownloadUrl'.

To download a file content the supplied user credentials must be approved to get access to the member's files.

The response body is the file content.

Where possible, the response headers Content-Disposition and Content-Type are set with content meta-data, such as filename.

Given the existing published Release Package:

The content for Release file 211928 can be downloaded using the value of the clientDownloadUrl.