R4 Overview
- Schema
- Service Root URL
- Client Errors
- Operation Outcomes
- Handling Required Fields
- General Security Filtering
- Authorization
- Pagination
- Cross Origin Resource Sharing
Cerner’s Soarian Clinicals® implementation currently supports both the R4 First Normative Content (4.0.1) version and DSTU 2 Final (1.0.2) version of the Health Level Seven (HL7)® International Fast Healthcare Interoperability Resources (FHIR)® standard. Cerner’s implementation of the R4 version is ongoing and new resources and actions will be added over time.
Existing DSTU 2 patient-facing applications will eventually need to be migrated to the Soarian Clinicals® FHIR® R4 implementation. For this reason, Cerner strongly encourages development against R4 whenever possible.
Schema
All API access are over HTTPS. See Service Root URL for more information on the URL format. All data are sent and received as JSON.
$ curl -i -H "Accept: application/fhir+json" https://fhir-myrecord-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/metadata HTTP/1.1 200 OK Date: Tue, 26 Mar 2019 15:50:49 GMT Cache-Control: no-cache Vary: Origin X-Request-Id: ecd13b72-4fde-11e9-8674-8b0a57a130fd Content-Type: application/json+fhir { "resourceType": "CapabilityStatement", "publisher": "Cerner Corporation", "date": "2021-09-06T03:25:46-04:00", "url": "https://fhir-myrecord-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/metadata", "name": "Soarian Clinicals Capability Statement", "title": "Soarian Clinicals Capability Statement", "status": "active", "description": "Cerner Soarian Clinicals FHIR API", "kind": "instance", "fhirVersion": "4.0.1", "format": [ "json", "application/json", "application/fhir+json", "application/json+fhir" ], "implementation": { "description": "Cerner Soarian Clinicals FHIR API", "url": "https://fhir-myrecord-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/metadata" }, "rest": [ { "mode": "server", "documentation": "Cerner Soarian Clinicals FHIR API", "security": { "extension": [ { "url": "http://fhir-registry.smarthealthit.org/StructureDefinition/oauth-uris", "extension": [ { "url": "token", "valueUri": "https://authorization.cerner.com/tenants/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/hosts/fhir-myrecord-sc.cerner.com/protocols/oauth2/profiles/smart-v1/token" }, { "url": "authorize", "valueUri": "https://authorization.cerner.com/tenants/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/protocols/oauth2/profiles/smart-v1/personas/patient/authorize" }, { "url": "introspect", "valueUri": "https://authorization.cerner.com/tokeninfo" }, { "url": "manage", "valueUri": "https://authorization.cerner.com/tenants/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/personas/patient/my-authorizations" } ] }, { "url": "http://cerner.hs.fhir.com/StructureDefinition/SoarianIdLinking-uris", "extension": [ { "url": "token", "valueUri": "https://authorization.cerner.com/tenants/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/protocols/oauth2/profiles/soarian-identity-linking-v1/token" }, { "url": "authorize", "valueUri": "https://authorization.cerner.com/tenants/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/protocols/oauth2/profiles/soarian-identity-linking-v1/personas/patient/authorize" } ] } ], "cors": true, "description": "OAuth2 with SMART extensions" }, "resource": [ { "type": "Condition", "profile": "http://hl7.org/fhir/condition", "interaction": [ { "code": "search-type" }, { "code": "read" } ], "searchParam": [ { "name": "_id", "definition": "http://hl7.org/fhir/SearchParameter/Resource-id", "type": "token", "documentation": "Bundle contains a Condition resource with the id requested plus any other search criteria." }, { "name": "patient", "definition": "http://hl7.org/fhir/SearchParameter/clinical-patient", "type": "reference", "documentation": "Bundle contains Condition resources for the patient requested plus any other search criteria." }, { "name": "encounter", "definition": "http://hl7.org/fhir/SearchParameter/Condition-encounter", "type": "reference", "documentation": "Bundle contains Condition resources for visit requested plus any other search criteria." }, { "name": "_revinclude", "definition": "http://hl7.org/fhir/search.html#revinclude", "type": "reference", "documentation": "Includes Provenance resource in response. It may only be provided if at least one other parameter is provided." } ], "searchRevInclude": [ "Provenance:target" ] }, { "type": "Immunization", "profile": "http://hl7.org/fhir/immunization", "interaction": [ { "code": "search-type" }, { "code": "read" } ], "searchParam": [ { "name": "_id", "definition": "http://hl7.org/fhir/SearchParameter/Resource-id", "type": "token", "documentation": "Fetches an Immunization resource by the logical id of the resource" }, { "name": "patient", "definition": "http://hl7.org/fhir/SearchParameter/clinical-patient", "type": "reference", "documentation": "Fetches a bundle of Immunization records for the specified patient." }, { "name": "_revinclude", "definition": "http://hl7.org/fhir/search.html#revinclude", "type": "reference", "documentation": "Includes Provenance resource in response. It may only be provided if at least one other parameter is provided." } ], "searchRevInclude": [ "Provenance:target" ] }, { "type": "MedicationRequest", "profile": "http://hl7.org/fhir/medicationrequest", "interaction": [ { "code": "search-type" }, { "code": "read" } ], "searchParam": [ { "name": "_id", "definition": "http://hl7.org/fhir/SearchParameter/Resource-id", "type": "token", "documentation": "Bundle contains a MedicationRequest resource with the id requested plus any other search criteria" }, { "name": "patient", "definition": "http://hl7.org/fhir/SearchParameter/clinical-patient", "type": "reference", "documentation": "Bundle contains MedicationRequest resources for the specified patient and requested [intent] plus any other criteria." }, { "name": "intent", "definition": "http://hl7.org/fhir/SearchParameter/MedicationRequest-intent", "type": "token", "documentation": "Bundle contains MedicationRequest resources for the specified patient and requested [intent] plus any other criteria." }, { "name": "status", "definition": "http://hl7.org/fhir/SearchParameter/medications-status", "type": "token", "documentation": "Bundle contains MedicationRequest resources for the specified patient and requested [intent] and requested [status] plus any other criteria." }, { "name": "encounter", "definition": "http://hl7.org/fhir/SearchParameter/medications-encounter", "type": "reference", "documentation": "Bundle contains MedicationRequest resources for the specified patient and requested [intent] and requested [encounter] plus any other criteria." }, { "name": "_revinclude", "definition": "http://hl7.org/fhir/search.html#revinclude", "type": "reference", "documentation": "Fetches all the MedicationRequest resources matching the search criteria and the Provenance resources for the result set." } ], "searchRevInclude": [ "Provenance:target" ] } ] } ] }
Blank fields are omitted.
All timestamps are returned in FHIR® standard date/dateTime formats.
Media Types
Soarian Clinicals® supports the R4 FHIR® standard defined media type for JSON content:
application/fhir+json
Soarian Clinicals® recommends that you explicitly request this accept type using the Accept
header, however, it’s not mandatory except places required by the HL7® FHIR® specification. In addition Soarian Clinicals® also supports following media types for JSON content for backward compatibility only and these are not recommended to be used for R4 FHIR® APIs:
Service Root URL
URLs for the FHIR® server vary according to the tenant (data source or client) being accessed, as well as other factors. If the application is a Substitutable Medical Applications and Reusable Technologies (SMART)® application, the service root url is provided at launch time. For standalone applications, the URL can be requested or configured when the application is set up to run against a specific tenant. SMART® applications make FHIR® calls against URLs of the following format:
:serviceRootURL/:resource[?:parameters]
Secure Sandbox
You can use the secure sandbox for testing an application with authorization. The service root URL for this instance is different if the patient or a patient’s proxy is logging in.
Patient or Patient’s Proxy Access: https://fhir-myrecord-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/:resource[?:parameters]
Non-Patient Access: https://fhir-ehr-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/:resource[?:parameters]
Open Sandbox
Cerner does not currently provide an open sandbox instance of Soarian Clinicals®. Please use the Secure Sandbox URL.
Resource
:resource
represents the FHIR® standard resource to access. Example: Patient
Parameters
Many API methods support optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:
$ curl -i -H "Accept: application/json+fhir" "https://fhir-myrecord-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/MedicationRequest?patient=4C05F5F357EE44FC874C0CF4AB249F99&status=active"
In this example, MedicationOrder is the FHIR® standard resource being accessed, while patient
and status
are passed in the query string.
Resource Identity
Please note that no IDs or identifiers in the Soarian Clinicals® EHR are intended to be used outside of the context of their complete URL. A complete URL is composed of the service root url, the resource, and the parameters (if any).
For example, you must take into account the entire URL and not simply the ID or resource + ID:
https://fhir-myrecord-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/Patient/4C05F5F357EE44FC874C0CF4AB249F99
In another context, the ID Patient/4C05F5F357EE44FC874C0CF4AB249F99 may identify another person entirely. In the following example, a different resource may be returned because the context (service root URL) has changed.
https://fhir-myrecord-sc.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Patient/4C05F5F357EE44FC874C0CF4AB249F99
Similarly, when considering an identifier, you must consider it only in its full context. Even though some identifiers may exist across multiple systems (for example, MRN), they may not refer to the same resource.
https://fhir-myrecord-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/Patient?identifier=urn:oid:1.1.1.1.1.1|1001006
For example, when using the above MRN in a different system, the same Patient resource may not be returned in the response bundle:
https://fhir-myrecord-sc.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d/Patient?identifier=urn:oid:1.1.1.1.1.1|1001006
Client Errors
Several possible types of client errors may occur on API calls that receive request bodies:
-
Failing to send a required query parameter or sending an unsupported parameter when the header processing preference is set to “handling=strict” results in a
400 Bad Request
response.HTTP/1.1 400 Bad Request no supported search parameters provided
-
Requesting the secure endpoint (non-
open
) without valid OAuth2 access token in the ‘Authorization’ header results in a401 Unauthorized
response.HTTP/1.1 401 Unauthorized
-
Requesting data from an unknown instance or an instance where the application or user is not authorized to access the requested resource or the patient results in a
403 Forbidden
response.HTTP/1.1 403 Forbidden
-
Requesting a resource that does not exist or that is masked by security results in a
404 Not Found
response.HTTP/1.1 404 Not Found
-
Requesting a media type other than application/json, application/fhir+json or application/json+fhir in the HTTP accept header will result in a
406 Not Acceptable
response.HTTP/1.1 406 Not Acceptable Content-Length: 0
-
Posting an unsupported media format will result in a
415 Unsupported Media Type
response.HTTP/1.1 415 Unsupported Media Type
Operation Outcomes
An OperationOutcome resource may be returned to provide additional context to an error. The following tables describe common operation outcomes and their causes.
HTTP Status | Cause | Severity | Code |
---|---|---|---|
400 | Format of the parameter list is invalid | error | structure |
400 | Required parameter missing | error | required |
400 |
• Code value or coding system not supported • Duplicate parameters error • Unsupported interaction • Unsupported operation • Unsupported parameter |
error | not-supported |
400 | Unexpected multiple matches for a given ID | error | multiple-matches |
400 | Too many results; narrow search | error | business-rule |
401 | Invalid token | error | Unknown |
403 |
• Persona missing from JWT claims • Unrecognized scope |
error | Security |
404 |
• Patient ID was merged to a target • No matching results |
error | not-found |
Handling Required Fields
-
An OperationOutcome resource may be returned to provide information regarding missing fields that are required by HL7® FHIR® or the US Core HL7® profile. This OperationOutcome resource contains the DataAbsentReason.
{ "coding": [ { "extension": [ { "url": "http://hl7.org/fhir/StructureDefinition/data-absent-reason", "valueCode": "unknown" } ] } ] }
General Security Filtering
Certain data may not be available to all applications or users. Encounter or organization security, privileges, and preferences may filter data.
Authorization
Cerner Ignite APIs for Soarian Clinicals® has an endpoint secured with OAuth 2.0 with support for SMART® Applications. Refer to the extensions on the Conformance.rest.security
element in the Soarian Clinicals® FHIR® R4 server metadata.
Scopes supported: launch, launch/patient, openid, fhirUser, offline_access, online_access, profile, patient/AllergyIntolerance.read, patient/Binary.read, patient/CarePlan.read, patient/CareTeam.read, patient/Condition.read, patient/Device.read, patient/DiagnosticReport.read, patient/DocumentReference.read, patient/Encounter.read, patient/Goal.read, patient/Immunization.read, patient/MedicationRequest.read, patient/Observation.read, patient/Patient.read, patient/Procedure.read, patient/Provenance.read, user/AllergyIntolerance.read, user/Binary.read, user/CarePlan.read, user/CareTeam.read, user/Condition.read, user/Device.read, user/DiagnosticReport.read, user/DocumentReference.read, user/Encounter.read, user/Goal.read, user/Immunization.read, user/MedicationRequest.read, user/Observation.read, user/Organization.read, user/Patient.read, user/Person.read, user/Practitioner.read, user/Procedure.read, user/Provenance.read, system/AllergyIntolerance.read, system/Binary.read, system/CarePlan.read, system/CareTeam.read, system/Condition.read, system/Device.read, system/DiagnosticReport.read, system/DocumentReference.read, system/Encounter.read, system/Goal.read, system/Immunization.read, system/MedicationRequest.read, system/Observation.read, system/Organization.read, system/Patient.read, system/Practitioner.read, system/Procedure.read, system/Provenance.read
Each resource interaction documents the type of acceptable authentication (patient, provider, or system). While an interaction may list system authentication, this functionality is currently not available in production.
See the authorization documentation for details on how to authorize using the Soarian Clinicals® FHIR® R4 server.
Pagination
The pagination links are included in the Bundle when a resource returns more items than the Bundle page size. It is important to follow these Links, rather than constructing your own URLs.
{
"resourceType": "Bundle",
"id": "f22ca456-19a7-45ce-8586-0079495783ef",
"type": "searchset",
"link": [
{
"relation": "self",
"url": "https://fhir-myrecord-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/Observation?patient=4C05F5F357EE44FC874C0CF4AB249F99&category=vital-signs&_count=50&_format=json"
},
{
"relation": "next",
"url": "https://fhir-myrecord-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/Observation?patient=4C05F5F357EE44FC874C0CF4AB249F99&category=vital-signs&_count=50&_format=json&page=2&pageBookmark=NRS.VS.15262"
}
],
...
}
The possible relation
values are:
Name | Description |
---|---|
self |
Shows the URL of the current page of results. |
next |
Shows the URL of the next sequential page of results. |
Search Result Currency
Developers need to account for data currency in the response. See the FHIR® specification, where HL7® states the following about this requirement:
“The results of a search operation are only guaranteed to be current at the moment the operation is executed. After the operation is executed, ongoing actions performed on the resources against which the search was executed will render the results increasingly stale. The significance of this depends on the nature of the search, and the kind of use that is being made of the results.”
This is particularly relevant when the server is returning the results in a series of pages. It is at the discretion of the search engine of how to handle ongoing updates to the resources while the search is proceeding.”
When results are returned in a series of pages, you may see the same resource ID on subsequent pages. Developers need to take this situation into account by filtering by resource ID and only return the latest version of that resource ID. Displaying duplicate resource IDs or any other manipulation may misrepresent the data, thus affecting clinical decision support and patient safety.
Cross Origin Resource Sharing
The API supports Cross Origin Resource Sharing (CORS) for AJAX requests from any origin. You can read the CORS W3C Recommendation, or this intro from the HTML 5 Security Guide.
Here’s a sample request sent from the origin http://example.com
:
$ curl -i -H "Origin: http://example.com" -H "Accept: application/json+fhir" https://fhir-myrecord-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/metadata HTTP/1.1 200 OK Access-Control-Allow-Origin: http://example.com Access-Control-Allow-Methods: GET, POST Access-Control-Max-Age: 0 Access-Control-Allow-Credentials: true
This is what a CORS preflight request looks like:
$ curl -X OPTIONS -i -H "Origin: http://example.com" https://fhir-myrecord-sc.cerner.com/r4/2f8f5ec1-b7b8-4be5-ae27-e308284dd9c1/metadata HTTP/1.1 204 No Content Access-Control-Allow-Origin: http://example.com Access-Control-Allow-Methods: GET, POST Access-Control-Max-Age: 0 Access-Control-Allow-Credentials: true