Programming Guide
This guide introduces some basic concepts and workflows that will be important as you begin using the API.
Input FHIR Bundle
All Insight API operations expect FHIR bundle as an input generated via the [Convert API]/convert).
If a bundle does not contain any patient resources, or contains multiple patient resources, the operation won’t be performed and an error will be returned.
If a resource in the input bundle references a patient other than the single patient resource in the bundle, that resource will not be included in the calculations of the derived data.
The Insight API only supports the following FHIR resources as part of the input bundle:
- Patient
- Condition
- Encounter
- Procedure
- Medication
- Observation
All other resources will be skipped.
Output FHIR Bundles
Insight API operations will return a FHIR R4 Bundle containing resources that together describe the resulting derived data. The bundle will be of type collection. The patient resource for which the derived data was calculated will always be included in the returned bundle.
OperationOutcomes
The output FHIR Bundle includes an OperationOutcome resource. An OperationOutcome is a collection of issue elements detailing what was parsed from the input, as well as any problems with the conversion. See Operation Outcomes for details.
Resource IDs
The Insight API will generate unique logical IDs for all new resources that were generated to describe the derived data concept. The returned patient resource will retain its input resource id.
Resources within a bundle may refer to other resources within the same bundle (e.g. a MeasureReport referencing a Patient/{ID}). The insight API is stateless, and different requests are considered independent of one another. Submitting the same input information to the API multiple times will result in different logical ID elements being generated for the equivalent input concept.
