Skip to content

GraphQL API

Jump to bottom
Kat edited this page May 27, 2021 · 13 revisions

We expose a GraphQL API for universal drug codes. This page is intended as a standalone reference guide to querying and retrieving data.

Query Details

  • Endpoint: {GraphQLHost}/v1/graphql

There are two options available for querying our GraphQL API, GET or POST.

POST

  • Headers: Content-Type: application/json
  • Body: { "query": [GRAPHQL_QUERY] "operationName": [OPERATION_NAME] }
  • Example: {"query":"query GetProductsByType {\n entities ( \n filter: \n { \n type: \"drug\"\n orderBy: {\n field: \"description\",\n descending: false\n },\n }\n offset: 0,\n first: 25\n ) \n {\n data {\n code \n description\n type\n }\n }\n}\n ","operationName":"GetProductsByType"}

GET

Tips on Querying

When building queries/testing against this API it is recommended to use a GraphQL client that does schema introspection (e.g. Insomnia/GraphiQL) for schema visibility and syntax highlighting/correction.

As these are all GraphQL requests, you may specify as many or as few properties (per the schema) as you require. Note that both children and properties are recursive and will need to be specified to the necessary depth as required in the query.

Examples

Below are some sample GraphQL queries that can be executed against the API, with corresponding sample responses.

Description Sample Query Sample Response
Finds a specific product and its properties via exact code. 
query GetProductsByCode {
  entity (code: "GH89P98W") {
    code 
    description
  }
}

{
  "data": {
    "entity": {
      "code": "GH89P98W",
      "description": "Paracetamol"
    }
  }
}
Interactions has been exposed as a separate entity. This will retrieve drug interaction data from rxnav (https://rxnav.nlm.nih.gov/api-Interaction.findDrugInteractions.html) 
query GetInteractionsByUC {
  interactions (
    code: "2d4f522e"
  )
  {
    rxcui
    errors { 
      message 
    }
    data {
      name
      description
      severity
      rxcui
    }
  }
}

{
  "data": {
    "interactions": {
      "rxcui": "1256",
      "errors": [],
      "data": [
        {
          "name": "Etanercept",
          "description": "The metabolism of Azathioprine can be increased when combined with Etanercept.",
          "severity": "N/A",
          "rxcui": "2462511"
        },
        [...]
      ]
    }
  }
}
A filter parameter is available when requesting products to filter the entity result collection.
Both 'offset' and 'first' are mandatory fields.

Filter parameters available are: 
code (string)
description (string)
orderBy (Object)
 - field (string)
 - descending (bool)
categories (string[])
  - 'Drug'
  - 'Consumable'
  - 'Other'
type (string)
  - drug
  - medicinal_product
  - form_category 
  - form
  - unit_of_use
match (string)
  - 'begins' (default)
  - 'contains'
  - 'exact'

query GetProductsByType {
  entities (     
    filter: 
    { 
      type: "drug" 
    }
    offset: 0,
    first: 10
  ) 
  {
    data {
      code 
      description
      type
    }
  }
}

{
    "data": {
        "entities": {
            "data": [
                {
                    "code": "c7750265",
                    "description": "Abacavir",
                    "type": "drug"
                },
                {
                    "code": "10c9701f",
                    "description": "Abacavir/Lamivudine",
                    "type": "drug"
                },
                {
                    "code": "33d71824",
                    "description": "Acetazolamide",
                    "type": "drug"
                },
                {
                    "code": "7c8c2b5b",
                    "description": "Acetic Acid",
                    "type": "drug"
                },
                [...]
            ]
        }
    }
}
A parameterless query for entities will default to returning all drugs.
Note that 'first' and 'offset' are mandatory 
query GetAllProducts {
  entities (
    filter: 
    { }
    offset: 0,
    first: 10
  )
  {
    data {
    # medicinal_product
    code 
    description
    type,
    interactions {
      name
    }
    properties {
      type
      value
      properties {
        type
        value
      }
    }
    children {
      # form_category
      code 
      description
      type
      properties {
        type
        value
      }
      children {
        # form
        code 
        description
        type
        children {
          # unit_of_use
          code 
          description
          type
          properties {
            type
            value
          }
          children {
            # product_pack
            code 
            description
            type
            properties {
              type
              value
              properties {
                type
                value
              }
            }
          }
        }
      }
    }
    }
  }
}

{
  "data": {
    "entities": [
      {
        "code": "GH89P98W",
        "description": "Paracetamol",
        "type": "medicinal_product",
        "properties": [
          {
            "type": "ddd",
            "value": "3g"
          },
          {
            "type": "atc_code",
            "value": "N02BE01"
          }
        ],
        "children": [
          "code": null,
          "description": "Paracetamol oral",
          "type": "form_category",
          "properties": null,
          "children": [ 
            [...]
          ]
        ],
      },
      {  
        "code": "QFWR9789",
        "description": "Amoxicillin",
        "type": "medicinal_product",
        "properties": [ 
          [...]
        ],
        "children": [ 
          [...]
        ]
      }
    ]
  }
}
Query that mSupply sends to UCS. For testing purposes 
query GetEntitiesByName {
  entities (
      filter: { 
        description: "Amo" 
        type: "drug unit_of_use medicinal_product" 
        orderBy: {
          field: "description"
          descending: false
        }
      },
      offset: 0,
      first: 25) 
  {
    data {
        code,
        description,
        type,
        product {
          properties {
            type
            value
          }
        }
        properties {
          type
          value
        }
    },
    totalLength 
  }
}

{
  "data": {
    "entities": {
      "data": [
        {
          "code": "35fa94bf",
          "description": "Amodiaquine Oral Tablet 153mg",
          "type": "strength",
          "product": {
            "properties": [
              {
                "type": "code_rxnav",
                "value": "720"
              },
              {
                "type": "who_eml",
                "value": "6.5.3.1"
              },
              {
                "type": "code_unspsc",
                "value": "51101913"
              }
            ]
          },
          "properties": [
            {
              "type": "who_eml",
              "value": "6.5.3.1"
            }
          ]
        },
        [...]
       ],
       "totalLength": 0
     }
   }
}

Disclaimer: This product uses publicly available data from the U.S. National Library of Medicine (NLM), National Institutes of Health, Department of Health and Human Services; NLM is not responsible for the product and does not endorse or recommend this or any other product.

Clone this wiki locally