🚧

Beta

This API is in a stage of development that may be subject to change or deprecation and may not yet be feature complete or perform consistently.

Getting started with GraphQL

GraphQL is a flexible data query language that allows you to request exactly the data you need, allowing for more efficient data retrieval. If you are new to the technology, here are some great educational resources:

• Introduction to GraphQL
• How to GraphQL
• Guides and Best Practices

The GraphQL API supports queries scoped to one human — FHIR resources associated with one Universal Patient Identifier — on resource types in the Designated Record Set. For simplicity, the patient will be referred to as one UPID.

Authentication

All GraphQL API queries require a valid access token. Include your bearer token as an Authorization header on all API queries. Learn more about getting started with authentication.

Endpoint

FHIR REST APIs have numerous endpoints. The GraphQL API has a single endpoint that remains constant no matter what query you perform. Queries are executed by sending POST HTTPS requests to the endpoint.

POST https://api.zusapi.com/fqs

Constraints and Limits

At this time,

• The GraphQL API follows the rate limits as defined in the Zus FAQs.
• The GraphQL API experiences interruptions querying for resource types with more than 10,000 resources of that type associated with one UPID.
• The GraphQL API does not guarantee immediate read-your-write consistency. There may be a delay between when data is written and when it becomes available for subsequent read operations, which can result in inconsistencies.

Forming a query

The Zus FHIR GraphQL Service is read-only and thus only allows the query operation, the equivalent of making a GET request in REST. GraphQL queries return only the data you specify. To form a query, you must specify fields within fields until you return only scalars.

📘

All queries require a mandatory UPID parameter, which defines the UPID against which to scope the search.

Query types

The GraphQL supports two query types: List and Connection. Whereas List queries do not support pagination or sorting, Connection queries do. The following query returns the address for all Patient resources associated with UPID 6a97a8ff-07fc-41b7-9284-487f29671146.

{
  PatientList(upid: "6a97a8ff-07fc-41b7-9284-487f29671146") {
    address {
      city
      country
      district
      line
      period {
        start
        end
      }
      postalCode
      state
      text
      type
      use
    }
  }
}

Connection

To consistently handle pagination best practices, the GraphQL API conforms to the GraphQL Cursor Connections Specification. In the query, the connection model provides a standard mechanism for slicing and paginating the result set. In the response, the connection model provides a standard way of providing cursors, and a way of telling the client when more results are available.

query {
  ConditionConnection (
    upid: "6a97a8ff-07fc-41b7-9284-487f29671146",
    first: 100, after: "") {
    pageInfo {
      hasNextPage
    }
    edges {
      node {
        id
        meta { lastUpdated }
      }
      cursor
    }
  }
}

In the example query above, ConditionConnection is a connection. The first argument to ConditionConnection asks to return 100 Condition FHIR resources. hasNextPage will inform you whether more edges are available or if the end of this connection has been reached. Moreover, a cursor was passed in for each edge in the connection. To get to the next page, use the after parameter and set it to the cursor (the resource ID) of the last resource in the result set.

query {
  ConditionConnection (
    upid: "6a97a8ff-07fc-41b7-9284-487f29671146",
    first: 100,
    after: "c8d5ce3c-fb11-4435-93f0-df2e9abbf22a") {
    pageInfo {
      hasNextPage
    }
    edges {
      node {
        id
        meta { lastUpdated }
      }
      cursor
    }
  }
}

Filtering

All List and Connection queries support an optional filter parameter. The filter parameter can be passed as follows:

query {  
  PatientList(upid: "6a97a8ff-07fc-41b7-9284-487f29671146", filter: <filter>) {  
  	id  
  }  
}

The object has the following syntax:

{
  <field1>: { <comparator1>: <value1> },
  <field2>: { <comparator2>: <value2> },
}

When multiple fields are included at the top level of the object, the criteria are ANDed together.

Comparators

The available comparators depend on the type of the field filter. The GraphQL API supports the following comparators:

Including referenced resources

Rather than have to conduct a separate query to retrieve a referenced resource of a different resource type, you can include a referenced resource in a result set through the resource element by leveraging fragments. For example, to include the id and name of the Organization resource referenced by a Patient resource through its managing organization:

query {  
  PatientList(upid: "6a97a8ff-07fc-41b7-9284-487f29671146" {  
		id
    meta {
        lastUpdated
        versionId
        tag {
            system
            code
        }
    }
    extension {
        url
        valueString
    }
    managingOrganization {
      resource {
        ... on Organization {
            id
            name
        }
      }
    }
  }
}