Skip to content
This repository has been archived by the owner on Aug 11, 2021. It is now read-only.

concepts

Jump to bottom
Jonathan Payne edited this page Feb 16, 2015 · 54 revisions

Table of Contents

Overview

Concepts

Concept Versions

Concept Names

Concept Descriptions

Extra Concept Metadata

Overview

The API exposes a representation of concepts. Concepts are stored in Sources, such as CIEL, ICD-10, or WHO-IMR. Collections provide versioned containers of references to concepts across sources.

Concepts have 3 fields that act as sub-resources: names, descriptions, and extras. This allows names, descriptions, and extra metadata to be referenced, viewed, edited, or deleted individually rather than as a whole. These fields are returned with the concept when requesting the full concept details (e.g. GET /orgs/WHO/sources/ICD-10-2010/concepts/A10.9/)

Concept Shorthand

Concepts are sometimes referred to in shorthand, rather than their fully specified URL:

# Get the latest version of a concept
org:source:concept

# Get the concept from a specific version of the source
org:source[sourceVersion]:concept

# Get a specific version of a concept 
org:source:concept[conceptVersion]

For example, each set points to the same three concepts:

  • Fully specified:
    • https://api.openconceptlab.org/v1/orgs/WHO/sources/ICD-10-2010/concepts/A10.9/
    • https://api.openconceptlab.org/v1/orgs/Regenstrief/sources/LOINC/2.43/concepts/32700-7/
    • https://api.openconceptlab.org/v1/orgs/MySDO/sources/RainMED/concepts/2962/1d35/
  • Short-hand:
    • WHO:ICD-10-2010:A10.9
    • Regenstrief:LOINC[2.43]:32700-7
    • MySDO:RainMED:2962[1d35]

Versioning of concepts

All changes to concepts are tracked internally. The latest version of a concept is retrieved if no version identifier (for the source or concept) is specified. If a source version identifier is specified, then the version of the concept at the time the source version was created is used. Alternatively, specific versions of concepts may also be retrieved.

Future Considerations

Get a single concept

  • Get the latest version of a single concept of a source owned by an organization or user
GET /orgs/:org/sources/:source/concepts/:concept/
GET /users/:user/sources/:source/concepts/:concept/
GET /user/sources/:source/concepts/:concept/
  • Get the concept from the specified version of the source
GET /orgs/:org/sources/:source/:sourceVersion/concepts/:concept/
GET /users/:user/sources/:source/:sourceVersion/concepts/:concept/
GET /user/sources/:source/:sourceVersion/concepts/:concept/
  • Get a specific version of a concept
GET /orgs/:org/sources/:source/concepts/:concept/:conceptVersion/
GET /users/:user/sources/:source/concepts/:concept/:conceptVersion/
GET /user/sources/:source/concepts/:concept/:conceptVersion/
  • Parameters
    • includeMappings (optional) string - default is "true"; set to "false" to not return mappings
    • includeInverseMappings (optional) string - default is "false"; set to "true" to return inverse mappings
  • Notes:
    • The field "is_latest_concept_version" is true if returned concept is the latest version of the concept; the field is omitted otherwise.
    • "previous_version" field is set to the UUID of the prior version of the concept, if it exists.
    • "names", "descriptions", and "extras" are returned in full along with the concept details.

Example Request

  • Get the current version of a concept from the WHO:ICD-10-2010
GET /orgs/WHO/sources/ICD-10-2010/concepts/A15.1/

Response

  • Status: 200 OK
{
    "type": "Concept",
    "uuid": "8d492ee0-c2cc-11de-8d13-0010c6dffd0f",
    "id": "A15.1",
    "external_uuid": "19jf93jf9j39fii399du9393",

    "concept_class": "Diagnosis",
    "datatype": "None",
    "retired": false,

    "display_name": "Tuberculosis of lung, confirmed by culture only",
    "display_locale": "en",

    "names": [
        {
            "type": "ConceptName",
            "uuid": "akdiejf93jf939f9",
            "external_uuid": "1fddfenkcineh9",
            "name": "Tuberculosis of lung, confirmed by culture only",
            "locale": "en",
            "locale_preferred": "true",
            "name_type": None
        },
        {
            "type": "ConceptName",
            "uuid": "90jmcna4-lkdhf78",
            "external_uuid": "12345677",
            "name": "Tuberculose pulmonaire, confirmée par culture seulement",
            "locale": "fr",
            "locale_preferred": "true",
            "name_type": None
        }
    ],
    "descriptions": [
        {
            "type": "ConceptDescription",
            "uuid": "aY873Hbmkdi09jeh",
            "external_uuid": "abcdefghijklmnopqrstuvwxyz",
            "description": "Tuberculous bronchiectasis, fibrosis of lung, pneumonia, pneumothorax, confirmed by sputum microscopy with culture only",
            "locale": "en",
            "locale_preferred": "true",
            "description_type": None
        }
    ],

    "extras": {
        "parent": "A15"
    },

    "source": "ICD-10-2010",
    "owner": "WHO",
    "owner_type": "Organization",

    "is_latest_concept_version": "true",
    "version": "abc345jf9fj",
    "previous_version": "10393930df3",

    "url": "https://api.openconceptlab.org/v1/orgs/WHO/sources/ICD-10-2010/concepts/A15.1/",
    "version_url": "https://api.openconceptlab.org/v1/orgs/WHO/sources/ICD-10-2010/concepts/A15.1/abc345jf9fj/",
    "source_url": "https://api.openconceptlab.org/v1/orgs/WHO/sources/ICD-10-2010/",
    "owner_url": "https://api.openconceptlab.org/v1/orgs/WHO/",
    "mappings_url": "https://api.openconceptlab.org/v1/orgs/WHO/sources/ICD-10-2010/concepts/A15.1/mappings/",
    "extras_url": "https://api.openconceptlab.org/v1/orgs/WHO/sources/ICD-10-2010/concepts/A15.1/extras/",

    "versions": 9,
    "stars": 6,           # NOT CURRENTLY IMPLEMENTED
    "collections": 2,     # NOT CURRENTLY IMPLEMENTED

    "created_on": "2008-01-14T04:33:35Z",
    "created_by": "johndoe",
    "updated_on": "2008-02-18T09:10:16Z",
    "updated_by": "johndoe"
}

List concepts for a specific source

  • List all concepts for an organization's source based on its current state - NOTE: Retired concepts are excluded by default
GET /orgs/:org/sources/:source/concepts/
  • List all concepts for a specific version of a source - NOTE: Retired concepts are excluded by default
GET /orgs/:org/sources/:source/:sourceVersion/concepts/
  • Parameters
    • verbose (optional) string - default is false; set to true to return full concept results instead of the concept summary
    • q (optional) string - search criteria
    • sortAsc/sortDesc (optional) string - sort results according to one of the following attributes: "lastUpdate" (default), "name"
    • concept_class (optional) string - filter results to those within a particular concept class, e.g. "laboratory procedure"
    • datatype (optional) string - filter results to those of a given datatype, e.g. "numeric"
    • locale (optional) string - filter results to those with a name for the given locale, e.g. "en", "fr"
    • includeRetired (optional) integer - 1 or 0, default 0
    • mapcode (optional) string - e.g. IHTSDO:SNOMED-CT:123455
    • includeMappings (optional) string - default is "true" if "verbose" is set to "true", "false" otherwise; set to "false" to not return mappings even if "verbose" is set to "true"
    • includeInverseMappings (optional) string - default is "false"; set to "true" to return inverse mappings

Example

GET /orgs/WHO/sources/ICD-10-2010/concepts/?q=tuberculosis

Response

  • Status: 200 OK
[
     {
        "id": "A15.1",
        "concept_class": "Diagnosis",
        "datatype": "None",
        "retired": false,
        "source": "ICD-10-2010",
        "owner": "WHO",
        "owner_type": "Organization",
        "owner_url": "https://api.openconceptlab.org/orgs/WHO/",
        "display_name": "Tuberculosis of lung, confirmed by culture only",
        "display_locale": "en",
        "version": "abc345jf9fj",
        "is_latest_concept_version": "true",
        "url": "https://api.openconceptlab.org/orgs/WHO/sources/ICD-10-2010/concepts/A15.1/",
        "version_url": "https://api.openconceptlab.org/v1/orgs/WHO/sources/ICD-10-2010/concepts/A15.1/abc345jf9fj/"
    }
]

List concepts across sources

  • List concepts across sources from all users and organizations - NOTE: Retired concepts are excluded by default
GET /concepts/
  • Parameters
    • verbose (optional) string - default is "false"; set to "true" to return full concept results instead of the concept summary
    • q (optional) string - search criteria
    • sortAsc/sortDesc (optional) string - sort results according to one of the following attributes: "lastUpdate" (default), "name"
    • concept_class (optional) string - filter results to those within a particular concept class, e.g. "laboratory procedure"
    • datatype (optional) string - filter results to those of a given datatype, e.g. "numeric"
    • locale (optional) string - filter results to those with a name for the given locale, e.g. "en", "fr"
    • includeRetired (optional) integer - 1 or 0, default 0
    • mapcode (optional) string - e.g. IHTSDO:SNOMED-CT:123455
    • user (optional) string - filter by the username of the owner of the concept's source; cannot be used with org
    • org (optional) string - filter by the organization name of the owner of the concept's source; cannot be used with user
    • includeMappings (optional) string - default is "true" if "verbose" is set to "true", "false" otherwise; set to "false" to not return mappings even if "verbose" is set to "true"
    • includeInverseMappings (optional) string - default is "false"; set to "true" to return inverse mappings

Example

GET /concepts/?q=tuberculosis

Response

  • Status: 200 OK
[
    {
        "id": "A15.1",
        "concept_class": "Diagnosis",
        "datatype": "None",
        "retired": false,
        "source": "ICD-10-2010",
        "owner": "WHO",
        "owner_type": "Organization",
        "owner_url": "https://api.openconceptlab.org/orgs/WHO/",
        "display_name": "Tuberculosis of lung, confirmed by culture only",
        "display_locale": "en",
        "version": "abc345jf9fj",
        "is_latest_concept_version": "true",
        "url": "https://api.openconceptlab.org/orgs/WHO/sources/ICD-10-2010/concepts/A15.1/",
        "version_url": "https://api.openconceptlab.org/v1/orgs/WHO/sources/ICD-10-2010/concepts/A15.1/abc345jf9fj/"
    }
]

Create new concept

  • Create a new concept in a source
POST /orgs/:org/sources/:source/concepts/
POST /users/:user/sources/:source/concepts/
POST /user/sources/:source/concepts/
  • Input
    • id (required) string - unique identifier for concept, e.g. 145939019, A15.1, etc.
    • external_uuid (optional) string - optional UUID from an external source
    • concept_class (required) string - classification of the concept (e.g. "Diagnosis", "Procedure", etc.)
    • datatype (optional) string - datatype for the concept (e.g. "Numeric", "String", "Coded")
    • names (required) list - at least one name is required
      • name (required) string - concept name
      • external_uuid (optional) string - optional UUID from an external source
      • locale (required) string - 2-character language code, e.g. "en", "es"
      • locale_preferred (optional) - "true" or "false", default is "false",
      • name_type (optional) - additional name descriptor, such as those used in SNOMED CT
    • descriptions (optional) list
      • description (required)
      • external_uuid (optional) string - optional UUID from an external source
      • locale (required)
      • locale_preferred (optional) - default is "false"
      • description_type (optional) - additional descriptor, such as those used in SNOMED CT
    • extras (optional) JSON dictionary - additional metadata for the resource
  • Notes
    • At least one name must be submitted when the concept is created in order to set the "display_name" and "display_locale" fields
    • "descriptions", "extras", and additional "names" may be submitted with the concept details, in addition to being created after the fact by posting to the sub-resource (e.g. POST /.../concepts/12845003/names/)

Example

  • POST /orgs/IHTSDO/sources/SNOMED-CT/concepts/
{
    "id": "12845003",
    "external_uuid": "12845003",
    "concept_class": "Laboratory Procedure",
    "datatype": "N/A",
    "names": [
        {
            "type": "ConceptName",
            "uuid": "akdiejf93jf939f9",
            "external_uuid": "14",
            "name": "Malaria smear",
            "locale": "en",
            "locale_preferred": "true",
            "name_type": "Designated Preferred Name"
        },
        {
            "type": "ConceptName",
            "uuid": "akdiejf93jf939f9",
            "external_uuid": "176",
            "name": "Malaria smear (procedure)",
            "locale": "en",
            "name_type": "Full Form of Descriptor"
        }
    ],

    "extras": {
        "UMLS_CUI": "C0200703",
        "ISPRIMITIVE": "1"
    }
}

Response

{
    "type": "Concept",
    "uuid": "8d492ee0-c2cc-11de-8d13-0010c6dffd02",
    "id": "12845003",
    "external_uuid": "12845003",

    "concept_class": "Laboratory Procedure",
    "retired": false,

    "names": [
        {
            "type": "ConceptName",
            "uuid": "akdiejf93jf939f9",
            "external_uuid": "14",
            "name": "Malaria smear",
            "locale": "en",
            "locale_preferred": "true",
            "name_type": "Designated Preferred Name"
        },
        {
            "type": "ConceptName",
            "uuid": "akdiejf93jf939f9",
            "external_uuid": "176",
            "name": "Malaria smear (procedure)",
            "locale": "en",
            "name_type": "Full Form of Descriptor"
        }
    ],

    "source": "SNOMED-CT",
    "owner": "IHTSDO",
    "owner_type": "Organization",

    "version": "73jifjibL83",
    "is_latest_concept_version": "true",

    "url": "https://api.openconceptlab.org/orgs/IHTSDO/sources/SNOMED-CT/concepts/12845003/",
    "version_url": "https://api.openconceptlab.org/orgs/IHTSDO/sources/SNOMED-CT/concepts/12845003/73jifjibL83/",
    "source_url": "https://api.openconceptlab.org/orgs/IHTSDO/sources/SNOMED-CT/",
    "owner_url": "https://api.openconceptlab.org/orgs/IHTSDO/",
    "mappings_url": "https://api.openconceptlab.org/v1/orgs/IHTSDO/sources/SNOMED-CT/concepts/12845003/mappings/",

    "versions": 1,
    "stars": 0,                  # NOT CURRENTLY IMPLEMENTED
    "collections": 0,            # NOT CURRENTLY IMPLEMENTED

    "created_on": "2008-01-14T04:33:35Z",
    "created_by": "johndoe",
    "updated_on": "2008-01-14T04:33:35Z",
    "updated_by": "johndoe",

    "extras": {
        "UMLS_CUI": "C0200703",
        "ISPRIMITIVE": "1"
    }
}

Edit concept

  • Edit a concept - note that this creates a new version of the concept
POST /orgs/:org/sources/:source/concepts/:concept/
POST /users/:user/sources/:source/concepts/:concept/
POST /user/sources/:source/concepts/:concept/
  • Input
    • external_uuid (optional) string - optional UUID from an external source
    • concept_class (optional) string - classification of the concept (e.g. Diagnosis, Procedure, etc.)
    • datatype (optional) string - datatype for the concept (e.g. Numeric, String, Coded)
    • names (optional)
      • name (optional) string -
      • external_uuid (optional) string - optional UUID from an external source
      • locale (optional) string - 2-character language code, e.g. "en", "es"
      • locale_preferred (optional) - "true" or "false", default is "false",
      • name_type (optional) - additional name descriptor, such as those used in SNOMED CT
    • descriptions (optional)
      • description (optional)
      • external_uuid (optional) string - optional UUID from an external source
      • locale (optional)
      • locale_preferred (optional) - default is "false"
      • description_type (optional) - additional description descriptor, such as those used in SNOMED CT
    • update_comment (optional) string - text describing the reason for the update; this is stored in the "concept_version" resource
  • Notes
    • "names", "descriptions", and "extras" may be submitted with the concept details to update, but note that this approach will replace all of the names, descriptions, or extras with the newly submitted values. Use the sub-resources to create, edit, or delete individual values (e.g. POST /.../concepts/12845003/names/19jfjf9j3j/)

Response

  • Status: 200 OK
  • Returns the full JSON representation of the updated concept (same as above)

Retire concept

  • Retire a concept
DELETE /orgs/:org/sources/:source/concepts/:concept/
  • Notes
    • DELETE does not actually delete the concept; a retired concept is a new version of the concept with "retired" set to true, so that by default it is not returned in searches unless specifically requested. The "retired" status also indicates to users that the concept should not be used.
  • Parameters
    • update_comment (optional) string - text describing the reason for retiring the concept; this field is saved to the concept version

Response

  • Status: 204 No Content

List versions of a concept

  • List all versions of a specific concept
GET /orgs/:org/source/:source/concepts/:concept/versions/
  • Notes
    • "is_latest_concept_version" is set to true if the version is the latest version of the concept
    • "is_root_concept_version" is set to true if the version is the initial submission (the "root") of the concept
    • "update_comment" is user-generated text describing the reason for the new version, similar to a GitHub commit comment
  • Parameters
    • verbose (optional) string - set to true to include the full concept details along with the version metadata

Response

  • If verbose is "false" (the default), then only the version metadata is returned:
Request: GET /orgs/WHO/sources/ICD-10/concepts/A15.1/versions/
Status: 200 OK

[
    {
        "version": "a93-3j8083-d993mf",
        "previous_version": "abc345jf9fj",
        "url": "https://api.openconceptlab.org/orgs/WHO/sources/ICD-10/concepts/A15.1/a93-3j8083-d993mf/",
        "previous_version_url": "https://api.openconceptlab.org/orgs/WHO/sources/ICD-10/concepts/A15.1/abc345jf9fj/",
        "version_created_on": "2009-01-14T04:33:35Z",
        "version_created_by": "johndoe",
        "is_latest_concept_version": "true",
        "update_comment": "Updated the descriptions"
    },
    {
        "version": "abc345jf9fj",
        "is_root_concept_version": "true",
        "url": "https://api.openconceptlab.org/v1/orgs/WHO/sources/ICD-10/concepts/A15.1/abc345jf9fj/",
        "version_created_on": "2008-01-14T04:33:35Z",
        "version_replaced_on": "2009-01-14T04:33:35Z",
        "version_created_by": "johndoe",
        "update_comment": "Initial submission"
    }
]
  • If verbose is "true", then the full concept details are returned with version metadata:
Request: GET /orgs/WHO/sources/ICD-10/concepts/A15.1/versions/?verbose=true
Status: 200 OK

[
    {
        "type": "ConceptVersion",
        "version": "a93-3j8083-d993mf",
        "previous_version": "abc345jf9fj",
        "url": "https://api.openconceptlab.org/orgs/WHO/sources/ICD-10/concepts/A15.1/a93-3j8083-d993mf/",
        "previous_version_url": "https://api.openconceptlab.org/orgs/WHO/sources/ICD-10/concepts/A15.1/abc345jf9fj/",
        "version_created_on": "2009-01-14T04:33:35Z",
        "version_created_by": "johndoe",
        "is_latest_concept_version": "true",
        "update_comment": "Updated the descriptions",
        "concept": {
            # Full concept details are included here, the same as if requesting:
            # GET /orgs/WHO/sources/ICD-10/concepts/A15.1/a93-3j8083-d993mf/
        }
    },
    {
        "type": "ConceptVersion",
        "version": "abc345jf9fj",
        "is_root_concept_version": "true",
        "url": "https://api.openconceptlab.org/v1/orgs/WHO/sources/ICD-10/concepts/A15.1/abc345jf9fj/",
        "version_created_on": "2008-01-14T04:33:35Z",
        "version_replaced_on": "2009-01-14T04:33:35Z",
        "version_created_by": "johndoe",
        "update_comment": "Initial submission",
        "concept": {
            # Full concept details are included here, the same as if requesting:
            # GET /orgs/WHO/sources/ICD-10/concepts/A15.1/abc345jf9fj/
        }
    }
]

Get a single concept name

  • Get a single concept name
GET /orgs/:org/source/:source/concepts/:concept/names/:name_id/
GET /users/:user/source/:source/concepts/:concept/names/:name_id/
GET /user/source/:source/concepts/:concept/names/:name_id/

Example

  • GET /orgs/IHTSDO/sources/SNOMED-CT/concepts/12845003/names/akdiejf93jf939f9/

Response

  • Status: 200 OK
{
    "type": "ConceptName",
    "uuid": "akdiejf93jf939f9",
    "external_uuid": "14",
    "name": "Malaria smear",
    "locale": "en",
    "locale_preferred": "true",
    "name_type": "Designated Preferred Name"
}

List concept names

  • List concept names
GET /orgs/:org/source/:source/concepts/:concept/names/
GET /users/:user/source/:source/concepts/:concept/names/
GET /user/source/:source/concepts/:concept/names/
  • Parameters
    • q (optional) string - search criteria (based on the name field)
    • locale (optional) string - filter by locale
    • name_type (optional) - filter by name_type

Example

  • GET /orgs/IHTSDO/sources/SNOMED-CT/concepts/12845003/names/

Response

  • Status: 200 OK
[
    {
        "type": "ConceptName",
        "uuid": "akdiejf93jf939f9",
        "external_uuid": "14",
        "name": "Malaria smear",
        "locale": "en",
        "locale_preferred": "true",
        "name_type": "Designated Preferred Name"
    },
    {
        "type": "ConceptName",
        "uuid": "a93-3j8083-d993mf",
        "external_uuid": "179",
        "name": "Malaria smear (procedure)",
        "locale": "en",
        "name_type": "Full Form of Descriptor"
    }
]

Create new concept name

  • Create a new concept name
POST /orgs/:org/source/:source/concepts/:concept/names/
POST /users/:user/source/:source/concepts/:concept/names/
POST /user/source/:source/concepts/:concept/names/
  • Input
    • name (required) string - name
    • external_uuid (optional) string - optional UUID from an external source
    • locale (required) string - 2-character language code, e.g. "en", "es"
    • locale_preferred (optional) - "true" or "false", default is "false",
    • name_type (optional) - additional name descriptor, such as those used in SNOMED CT
  • Notes
    • Concept names are part of a concept, therefore creating a concept name will generate a new version of the underlying concept

Example

  • POST /orgs/IHTSDO/sources/SNOMED-CT/concepts/12845003/names/
{
    "name": "Malaria smear",
    "external_uuid": "14",
    "locale": "en",
    "locale_preferred": "true",
    "name_type": "Designated Preferred Name"
}

Response

{
    "type": "ConceptName",
    "uuid": "akdiejf93jf939f9",
    "external_uuid": "14",
    "name": "Malaria smear",
    "locale": "en",
    "locale_preferred": "true",
    "name_type": "Designated Preferred Name"
}

Edit concept name

  • Edit concept name
POST /orgs/:org/source/:source/concepts/:concept/names/:name_id/
POST /users/:user/source/:source/concepts/:concept/names/:name_id/
POST /user/source/:source/concepts/:concept/names/:name_id/
  • Input
    • name (required) string - name
    • external_uuid (optional) string - optional UUID from an external source
    • locale (required) string - 2-character language code, e.g. "en", "es"
    • locale_preferred (optional) - "true" or "false", default is "false",
    • name_type (optional) - additional name descriptor, such as those used in SNOMED CT
  • Notes
    • Concept names are part of a concept, therefore updating a concept name will generate a new version of the underlying concept

Example

  • POST /orgs/IHTSDO/sources/SNOMED-CT/concepts/12845003/names/akdiejf93jf939f9/
{
    "name": "Malaria smear and banana sundae"
}

Response

  • Status: 200 OK
{
    "type": "ConceptName",
    "uuid": "akdiejf93jf939f9",
    "external_uuid": "14",
    "name": "Malaria smear and banana sundae",
    "locale": "en",
    "locale_preferred": "true",
    "name_type": "Designated Preferred Name"
}

Delete concept name

  • Delete concept name
DELETE /orgs/:org/source/:source/concepts/:concept/names/:name_id/
DELETE /users/:user/source/:source/concepts/:concept/names/:name_id/
DELETE /user/source/:source/concepts/:concept/names/:name_id/
  • Notes
    • Concept names are part of a concept, therefore deleting a concept name will generate a new version of the underlying concept

Example

  • DELETE /orgs/IHTSDO/sources/SNOMED-CT/concepts/12845003/names/akdiejf93jf939f9/

Response

  • Status: 204 No Content

Get a single concept description

  • Get a single concept description
GET /orgs/:org/source/:source/concepts/:concept/descriptions/:description_id/
GET /users/:user/source/:source/concepts/:concept/descriptions/:description_id/
GET /user/source/:source/concepts/:concept/descriptions/:description_id/

Example

  • GET /orgs/IHTSDO/sources/SNOMED-CT/concepts/12845003/descriptions/aY873Hbmkdi09jeh/

Response

  • Status: 200 OK
{
    "type": "ConceptDescription",
    "uuid": "aY873Hbmkdi09jeh",
    "external_uuid": "9390",
    "description": "Tuberculous bronchiectasis, fibrosis of lung, pneumonia, pneumothorax, confirmed by sputum microscopy with culture only",
    "locale": "en",
    "locale_preferred": "true",
    "description_type": None
}

List concept descriptions

  • List concept descriptions
GET /orgs/:org/source/:source/concepts/:concept/descriptions/
GET /users/:user/source/:source/concepts/:concept/descriptions/
GET /user/source/:source/concepts/:concept/descriptions/
  • Parameters
    • q (optional) string - search criteria (based on the description field)
    • locale (optional) string - filter by locale
    • description_type (optional) - filter by description_type

Example

  • GET /orgs/IHTSDO/sources/SNOMED-CT/concepts/12845003/descriptions/

Response

  • Status: 200 OK
[
    {
        "type": "ConceptDescription",
        "uuid": "aY873Hbmkdi09jeh",
        "external_uuid": "9390",
        "description": "Tuberculous bronchiectasis, fibrosis of lung, pneumonia, pneumothorax, confirmed by sputum microscopy with culture only",
        "locale": "en",
        "locale_preferred": "true",
        "description_type": None
    },
    {
        "type": "ConceptDescription",
        "uuid": "99fhfhufeh-9ehAAB",
        "external_uuid": "393930",
        "description": "Another less relevant and more lengthy description here",
        "locale": "en",
        "locale_preferred": "false",
        "description_type": None
    }
]

Create new concept description

  • Create a new concept description
POST /orgs/:org/source/:source/concepts/:concept/descriptions/
POST /users/:user/source/:source/concepts/:concept/descriptions/
POST /user/source/:source/concepts/:concept/descriptions/
  • Input
    • description (required) string - description
    • external_uuid (optional) string - optional UUID from an external source
    • locale (required) string - 2-character language code, e.g. "en", "es"
    • locale_preferred (optional) - "true" or "false", default is "false",
    • description_type (optional) - additional description descriptor, such as those used in SNOMED CT
  • Notes
    • Concept descriptions are part of a concept, therefore creating a concept description will generate a new version of the underlying concept

Example

  • POST /orgs/IHTSDO/sources/SNOMED-CT/concepts/12845003/descriptions/
{
    "description": "Tuberculous bronchiectasis, fibrosis of lung, pneumonia, pneumothorax, confirmed by sputum microscopy with culture only",
    "locale": "en",
    "locale_preferred": "true"
}

Response

{
    "type": "ConceptDescription",
    "uuid": "aY873Hbmkdi09jeh",
    "external_uuid": "9390",
    "description": "Tuberculous bronchiectasis, fibrosis of lung, pneumonia, pneumothorax, confirmed by sputum microscopy with culture only",
    "locale": "en",
    "locale_preferred": "true",
    "description_type": None
}

Edit concept description

  • Edit concept description
POST /orgs/:org/source/:source/concepts/:concept/descriptions/:description_id/
POST /users/:user/source/:source/concepts/:concept/descriptions/:description_id/
POST /user/source/:source/concepts/:concept/descriptions/:description_id/
  • Input
    • description (required) string -
    • external_uuid (optional) string - optional UUID from an external source
    • locale (required) string - 2-character language code, e.g. "en", "es"
    • locale_preferred (optional) - "true" or "false", default is "false",
    • description_type (optional) - additional description descriptor, such as those used in SNOMED CT
  • Notes
    • Concept descriptions are part of a concept, therefore updating a concept description will generate a new version of the underlying concept

Example

  • POST /orgs/IHTSDO/sources/SNOMED-CT/concepts/12845003/descriptions/aY873Hbmkdi09jeh/
{
    "description": "Culture-only confirmation of tuberculous bronchiectasis, fibrosis of lung, pneumonia, or pneumothorax"
}

Response

  • Status: 200 OK
{
    "type": "ConceptDescription",
    "uuid": "aY873Hbmkdi09jeh",
    "external_uuid": "9390",
    "description": "Culture-only confirmation of tuberculous bronchiectasis, fibrosis of lung, pneumonia, or pneumothorax",
    "locale": "en",
    "locale_preferred": "true",
    "description_type": None
}

Delete concept description

  • Delete concept description
DELETE /orgs/:org/source/:source/concepts/:concept/descriptions/:description_id/
DELETE /users/:user/source/:source/concepts/:concept/descriptions/:description_id/
DELETE /user/source/:source/concepts/:concept/descriptions/:description_id/
  • Notes
    • Concept descriptions are part of a concept, therefore deleting a concept description will generate a new version of the underlying concept

Example

  • DELETE /orgs/IHTSDO/sources/SNOMED-CT/concepts/12845003/descriptions/aY873Hbmkdi09jeh/

Response

  • Status: 204 No Content

Get a single extra

  • Get a single extra
GET /orgs/:org/source/:source/concepts/:concept/extras/:field_name/
GET /users/:user/source/:source/concepts/:concept/extras/:field_name/
GET /user/source/:source/concepts/:concept/extras/:field_name/

Example

  • GET /orgs/IHTSDO/sources/SNOMED-CT/concepts/12845003/extras/isprimitive/

Response

  • Status: 200 OK
{
    "isprimitive": "true"
}

List all extras

  • List all extras
GET /orgs/:org/source/:source/concepts/:concept/extras/
GET /users/:user/source/:source/concepts/:concept/extras/
GET /user/source/:source/concepts/:concept/extras/

Response

  • Status: 200 OK
{
    "isprimitive": "true",
    "UMLS_CUI": "C0200703",
    "list-data": [ "1", "ab" ],
    "dictionary-data": { "more": "data" }
}

Create or Update an extra

  • Create or update an extra
PUT /orgs/:org/source/:source/concepts/:concept/extras/:field_name/
PUT /users/:user/source/:source/concepts/:concept/extras/:field_name/
PUT /user/source/:source/concepts/:concept/extras/:field_name/
(was POST)
  • Notes
    • Extras are part of a concept, therefore creating or updating an extra will generate a new version of the underlying concept

Example

  • PUT /orgs/IHTSDO/sources/SNOMED-CT/concepts/12845003/extras/isprimitive/
{
    "isprimitive": "false"
}

Response

  • Status: 200 OK
{
    "isprimitive": "false"
}

Delete an extra

  • Delete an extra
DELETE /orgs/:org/source/:source/concepts/:concept/extras/:field_name/
DELETE /users/:user/source/:source/concepts/:concept/extras/:field_name/
DELETE /user/source/:source/concepts/:concept/extras/:field_name/
  • Notes
    • Extras are part of a concept, therefore deleting an extra will generate a new version of the underlying concept

Example

  • DELETE /orgs/IHTSDO/sources/SNOMED-CT/concepts/12845003/extras/isprimitive/

Response

  • Status: 204 No Content

Issues

  • Currently "mappings" is always returned with concept details but is always empty. Fix this bug by populating the "mappings" attribute and add a new URL parameter "includeInverseMappings" which defaults to "false". Also consider adding a new URL parameter "includeMappings" which defaults to "true".
  • Ability to filter concept search by "mapcode" is not yet implemented.
  • "is_latest_concept_version" attribute is not yet implemented in concept details.
  • Currently "display" and "display_locale" are hard coded rather than dynamic attributes set according to the current user's preferences and the concept values.
  • Concept details spec has attributes of the count of "stars" and "collections" -- these are not currently implemented.
  • Need to confirm implementation of "sortAsc" and "sortDesc"
  • Need to add method to actually delete a concept, e.g. DELETE /.../?purge=true

Additional Resources

Overview

Resources

Import / Export

Troubleshooting & Operations

Other

Clone this wiki locally