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.
Method
Description
List all release packages. [code] $ curl -i 'https://mlds.ihtsdotools.org/api/releasePackages' [/code]
Name
Type
Description
Name
Type
Description
Add a new release file to a Release Version.
Name
Type
Description
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.
Name
Type
Description
A license document can be associated with a Release Package. [code] POST /api/releasePackages/:releasePackageId/license [/code]
Name
Type
Description
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.
DELETE
Delete a resource.
description
string
Description of the Release Package. Can be plain text or HTML.
publishedAt
date
Optional - The publish date of the Released Version. Format: YYYY-MM-DD
online
boolean
True if the release version is available to affiliates to download
GET
Retrieve a representation of the resource.
POST
Create a new resource.
PUT
Replace a resource.
member.key
string
Member organization, either IHTSDO or the two letter country code of the member country
name
string
Name of the Release Package
name
string
Name of the Release Version
description
string
Description of the Release Version. Can be plain text or HTML.
label
string
Short description of the file
downloadUrl
string
URL of file content
name
string
Name of the Release Version
description
string
Description of the Release Version. Can be plain text or HTML.
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.
Where possible the API supports appropriate HTTP Methods/Verbs for each resource.
Method
Description
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]
Name
Type
Optional
Description
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.
DELETE
Delete a resource.
Mandatory
Search keyword within the affiliate record. This will match against a number of identifying fields of the affiliate: organization name, first name, last name, street address, email, alternative email, and third email.
affiliateId
string
Optional
Limit the search to a specific Affilate record.
GET
Retrieve a representation of the resource.
POST
Create a new resource.
PUT
Replace a resource.
member
string
Mandatory
Identification of the member country that the affiliate has been accepted by. It is either a two-letter country code or IHTSDO to indicate IHTSDO international. The country codes are a subset of the ISO 3166-1 alpha-2 codes. 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.
$ curl -i 'https://mlds.ihtsdotools.org/api/affiliates/check?member=SE&match=abc@test.com' HTTP/1.1 200 OK Content-Type: application/json
{"matched":true}
$ curl -i 'https://mlds.ihtsdotools.org/api/affiliates/check?member=SE&match=abc@test.com' HTTP/1.1 200 OK Content-Type: application/json
{"matched":false}
$ curl -i 'https://mlds.ihtsdotools.org/api/affiliates/check?member=IHTSDO&match=hospital&affiliateId=123' HTTP/1.1 200 OK Content-Type: application/json
{"matched":true}
$ curl -i 'https://mlds.ihtsdotools.org/api/affiliates/check?member=IHTSDO&match=me%2Bwork@email.com' HTTP/1.1 200 OK Content-Type: application/json
{"matched":true}
MLDS Syndication
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.
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.
The extensions to the specification are as follows:
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.
Edition packages
Should contain the word edition
Should NOT contain the word extension
For example, titles following these conventions are
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
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
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
Extension packages
Should contain the word extension
Should NOT contain the word edition
The version of the package should be included in the title
The RF2 Release Type Full/Snapshot should be included as a bracketed suffix to the title
length - the size of the file in bytes, e.g. length="533422481"
Checksum validity. either of the two following values can be used (chosen by the distributor):
sct:md5Hash the MD5 hash function producing a 128-bit hash value used to check the validity of the file, e.g. sct:md5Hash="0290ad7f6e431063166afd91cd2b8c37"
ncts:sha256Hash the SHA256 hash function producing a 256-bit hash value used to check the validity of the file, e.g. sha256Hash="902ec61f6ada329bfd6bc487fe7adab0"
SCT_RF2_DELTA: Containing only Delta RF2 release files