|
|
| (44 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| − | this page contains early/provisional notes related to the development of a standard approach for use of graphQL with FHIR.
| + | This page moved to [[http://build.fhir.org/graphql.html http://build.fhir.org/graphql.html]] |
| − | | |
| − | Note: this page anticipates community agreement around a standard interoperable graphql interface for FHIR servers. There is always other ways to use graphQL with FHIR, which are useful and valid, *and are not prohibited* (if they are other end-points).
| |
| − | | |
| − | For discussion, see [[https://chat.fhir.org/#narrow/stream/implementers/subject/GraphQL chat.fhir.org]]
| |
| − | | |
| − | == Goals ==
| |
| − | | |
| − | The graphql functionality should be described by a schema
| |
| − | | |
| − | == Invoking GraphQL ==
| |
| − | | |
| − | For reasons of consistency with other aspects of FHIR, the standard end points for graphQL are
| |
| − | | |
| − | [base]/$graphql
| |
| − | [base]/[Type]/[id]/$graphql
| |
| − | | |
| − | GraphQL can be invoked by get with a query parameter, or a POST with the graphQL as the body, or a JSON body. (see [[http://graphql.org/learn/serving-over-http/]].
| |
| − | | |
| − | The mime type of the response is application/json. Non JSON responses are not described by the specification.
| |
| − | | |
| − | === Invocation Context ===
| |
| − | | |
| − | * System level ([base]/$graphql) - the query must start by selecting a resource type and some search criteria (see below)
| |
| − | * Resource Instance level ([base]/[Type]/[id]/$graphql) - the query assumes a single resource is in scope
| |
| − | | |
| − | | |
| − | == Data type mappings ==
| |
| − | | |
| − | Primitive Data types:
| |
| − | | |
| − | * FHIR integer | decimal | unsignedInt | positiveInt allmap to graphQL number
| |
| − | * FHIR boolean | code map to graphQL name
| |
| − | * All other FHIR primitive types map to graphQL string
| |
| − | | |
| − | Complex Data Types:
| |
| − | * Names are unchanged
| |
| − | | |
| − | == Error handling ==
| |
| − | | |
| − | Servers SHALL return an error when fields that do not exist are used, or when arguments, types, directives that are not recognised or supported are encountered
| |
| − | | |
| − | == Field Selection ==
| |
| − | | |
| − | Any FHIR defined field can be used directly e.g. this graphql against the Patient resource (r3)
| |
| − | | |
| − | {
| |
| − | name { text given family }
| |
| − | }
| |
| − | | |
| − | Polymorphic fields are represented by their JSON property name E.g. for Observation.value[x]:
| |
| − | | |
| − | {
| |
| − | valueQuantity { value units }
| |
| − | }
| |
| − | | |
| − | Note: This is because the leafs names have to correspond to scalar types, so there is no use selecting all the variants at once
| |
| − | | |
| − | === Field Arguments ===
| |
| − | | |
| − | Primitive fields SHALL not have any arguments at all.
| |
| − | | |
| − | Complex fields may have one of more of the following parameters:
| |
| − | | |
| − | * "fhirpath" - a fhir path statement selecting which of the subnodes is to be included. e.g.
| |
| − | {
| |
| − | name(fhirpath: "family.exists()") { text given family }
| |
| − | }
| |
| − | | |
| − | | |
| − | * "[field]" - the name of a sub-property with a specified value that must be matched for the field to be included. e.g.
| |
| − | {
| |
| − | name(use: official) { text given family }
| |
| − | }
| |
| − | | |
| − | | |
| − | === Additional Selectors ===
| |
| − | | |
| − | An object of type reference can have an additional selection "resource". This is an instruction to the server to resolve the reference, and then include the contents of the resource as specified by sub-selections in the property name "resource" (can be aliased).
| |
| − | | |
| − | e.g. On Observation:
| |
| − | {
| |
| − | subject { reference, resource {active} }
| |
| − | }
| |
| − | | |
| − | | |
| − | The resource selector has two arguments:
| |
| − | | |
| − | * optional : true | false. (default is false). If the server cannot resolve the reference, and optional is not true, the server returns an error instead of the graph output
| |
| − | * type : [Resource] - only selects resources of a particular type. Note that this is similar in effect to
| |
| − | | |
| − | {
| |
| − | id
| |
| − | subject {
| |
| − | reference
| |
| − | resource {
| |
| − | ...on Patient {
| |
| − | birthDate
| |
| − | }
| |
| − | ...on Practioner {
| |
| − | practitionerRole { speciality }
| |
| − | }
| |
| − | }
| |
| − | code {coding {system code} }
| |
| − | }
| |
| − | | |
| − | but slightly denser:
| |
| − | | |
| − | {
| |
| − | id
| |
| − | subject {
| |
| − | reference
| |
| − | resource(type : Patient) { birthDate }
| |
| − | resource(type : Practioner) { practitionerRole { speciality } }
| |
| − | }
| |
| − | code {coding {system code} }
| |
| − | }
| |
| − | | |
| − | == Searching resources ==
| |
| − | | |
| − | global system scope... todo...
| |
| − | | |
| − | == open questions ==
| |
| − | | |
| − | * How to do polymorphic fields
| |
| − | * how to do reverse references (e.g. include resources that reference the one in focus)
| |
| − | * polymorphic fields
| |
| − | * need for directives?
| |
| − | * extensions in primitive fields / schema reconciliation
| |
| − | * searching resources (.e.g context [base]/$graphql)
| |
| − | * backwards reference resolution
| |
| − | * mutations
| |
