R4 Overview
This topic describes the R4 (4.0.1) specification.
Oracle 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 is over HTTPS. See Service Root URL for more information on URL format. All data is 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:
Client Errors
There are several possible types of client errors 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 a
401 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 which 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 may be returned to provide additional context to an error. The tables below describes common OperationOutcomes 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 |
|
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 |
|
error |
Security |
404 |
|
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
Oracle 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 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 topics for more information.
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 Link header values instead of 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 |
---|---|
|
Shows the URL of the current page of results. |
|
Shows the URL of the next sequential page of results. |
Search Result Currency
Developers need to account for data currency within 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 GET 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