GraphQL API
Aidbox supports default GraphQL implementation without any extensions (specification)
Queries are supported, but mutations are not.
In Aidbox UI there is GraphiQL interface, you can try your queries there.
GraphQL console sends all your requests to
$graphql
endpoint which you can use from your application toopost
/$graphql
GraphQL endpoint
Aidbox generates different GraphQL scalars, objects, queries with arguments and unions from FHIR metadata.
For each ResourceType these queries are generated:
<resourceType>
— get fields of the specified resource. Accepts a single argumentid
and returns a resource with the specifiedid
. Example:Patient (id: "pat-1")
\<resourceType>List
— search resources of given resource type. Accepts FHIR search parameters for that resourceType. SearchParameters have underscores instead of dashes and referenced later in this documentation assearch_parameter
. For each SearchParameter two arguments are generated:<search_parameter>
e.g.:PatientList(address_state: "CA")
Accepts a string. Is an equivalent of using FHIR search parameter<search_parameter>_list
e.g.:PatientList(language_list: ["en", "de"])
Accepts a list of strings. It is an equivalent of repeating search parameters in FHIR search.<search_parameter>_list
arg is needed because args can't be repeated in the GraphQL query.
<resourceType>History
— get resource history. Acceptsid
argument and returns history of the resource with the specifiedid
. Example:PatientHistory(id: "pt1", _sort: "txid") {name}
PatientList(language_list: ["en", "de"])
will return a set of Patients the same asGET /Patient?language=en&language=de
and those will be patients withen
ANDde
as their communication language specified\PatientList(language: "en,de")
will return a set of Patients the same asGET /Patient?language=en,de
and those will be patients withen
ORde
as their communication language specified\PatientList(language_list: ["en", "de,fr"])
will return a set of Patients the same asGET /Patient?language=en&language=de,fr
and those will be patients withen
AND (de
ORfr
) as their communication language specified\PatientList(language: "en", language: "de")
is an error, it will ignore alllanguage
arg repetitions except of the last and will return a set of Patients the same asGET /Patient?language=de
For each ResourceType object with fields is generated.
For every FHIR resource attribute field is created.
Also for attributes with Reference type unions are created for direct and reverse includes.
FHIR GraphQL does not support _revinclude Search parameter. In Aidbox you can use reverse include in such format:
<revIncludeResourceType>s_as_<path_to_reference_field>
Here
revIncludeResourceType
should be lowercase name of a resource; path_to_reference_field
is a path to the field with type reference, where path separator is underscore (_
).For example:
observations_as_subject
for Patient will be equivalent of _revinclude=Observation:subject
Here's an example showing how to create first class extension, search parameter and use it in GraphQL:
First Class Extension
Search Parameter
ServiceRequest
GraphQL
Response
PUT /Attribute/ServiceRequest.requestedOrganizationDepartment
description: Department in the organization that made the service request
resource: {id: ServiceRequest, resourceType: Entity}
path: [requestedOrganizationDepartment]
type: {id: Reference, resourceType: Entity}
refers:
- Organization
extensionUrl: urn:extension:requestedOrganizationDepartment
PUT /SearchParameter/ServiceRequest.requestedOrganizationDepartment
name: requestedOrganizationDepartment
type: reference
resource: {id: ServiceRequest, resourceType: Entity}
expression: [[requestedOrganizationDepartment]]
PUT /ServiceRequest/sr3
intent: plan
status: final
subject:
id: pt1
resourceType: Patient
requestedOrganizationDepartment:
id: org2
resourceType: Organization
id: sr3
resourceType: ServiceRequest
query {
OrganizationList(_count: 5) {
id,
servicerequests_as_requestedOrganizationDepartment{
id
}
}
}
{
"data": {
"OrganizationList": [
{
"id": "org-1",
"servicerequests_as_a": []
},
{
"id": "org2",
"servicerequests_as_a": [
{
"id": "sr3"
}
]
}
]
}
}
Example of fragments usage. Get id of DeviceRequestList resource, add address of Organizations and Practitioners referenced in DeviceRequestList.requester:
query {
DeviceRequestList {
id,
requester {
resourceType
resource {
... on Organization {
id,
address {
use
}
}
... on Practitioner {
id,
address {
use
}
}
}
}
}
}
This example demonstrates how to use fragments, both types of search parameter arguments and reverse includes.
Request
Response
{
"query" : "
fragment PractitionerRoleWithPractitioner on PractitionerRole {
id
code {
coding {
code
system
display
}
}
practitioner {
resource {
... on Practitioner {
id
name {
given
}
}
}
}
}
{
PatientList(active: true, identifier_list: [\"tenantId|org1\", \"mrn|5678\"]) {
id
name {
given
}
generalPractitioner {
resource {
...PractitionerRoleWithPractitioner
}
}
observations_as_subject {
id
code {
coding {
code
system
display
}
}
performer {
resource {
...PractitionerRoleWithPractitioner
}
}
}
}
}
"}
{
"data" : {
"PatientList" : [ {
"id" : "51f507b5-8723-4dda-bee6-d3cbd86da28f",
"name" : [ {
"given" : [ "Tom" ]
} ],
"generalPractitioner" : [ {
"resource" : {
"id" : "54513486-7b9c-4baf-84b6-8d1bdb279ba3",
"code" : [ {
"coding" : [ {
"code" : "therapist",
"system" : "sys",
"display" : "Therapist"
} ]
} ],
"practitioner" : {
"resource" : {
"id" : "0091e1ee-8a5b-45a1-a1be-c2638e6ed482",
"name" : [ {
"given" : [ "Doc" ]
} ]
}
}
}
} ],
"observations_as_subject" : [ {
"id" : "68100e43-4d1c-4fb7-b4d9-2f14d359fe90",
"code" : {
"coding" : [ {
"code" : "15074-8",
"system" : "http://loinc.org",
"display" : "Glucose"
} ]
},
"performer" : [ {
"resource" : {
"id" : "54513486-7b9c-4baf-84b6-8d1bdb279ba3",
"code" : [ {
"coding" : [ {
"code" : "therapist",
"system" : "sys",
"display" : "Therapist"
} ]
} ],
"practitioner" : {
"resource" : {
"id" : "0091e1ee-8a5b-45a1-a1be-c2638e6ed482",
"name" : [ {
"given" : [ "Doc" ]
} ]
}
}
}
} ]
} ]
} ]
}
}
By default, Aidbox does in memory index cache warmup when the first request comes in.
You can change it to warmup cache on startup.
BOX_FEATURES_GRAPHQL_WARMUP__ON__STARTUP=true
Last modified 8d ago