RESTful Interactions
Health Gorilla FHIR APIs use standard REST conventions to retrieve, create, update, or delete clinical data. These interactions follow the HL7 specification and enable reliable, predictable communication between your system and the Health Gorilla platform.
HTTP Methods
Use the following HTTP verbs to perform FHIR operations:
| Method | Purpose | Example Use Case |
|---|---|---|
GET | Retrieve a resource or search a collection | Search for Observations by patient and date |
POST | Create a resource or invoke an operation | Submit a new DocumentReference or trigger $p360-retrieve |
PUT | Update a full resource | Replace patient demographic information |
DELETE | Remove a resource (limited use) | Delete test data in non-production environments |
Request Format
All FHIR interactions use JSON payloads with the following headers:
| Header | Description |
|---|---|
Content-Type | application/fhir+json |
Accept | application/fhir+json |
Authorization | Bearer {access_token} |
Accept-Encoding | gzip (optional for response compression) |
Search Interactions
Perform search operations using GET with query parameters. Always include the patient parameter when retrieving clinical data.
Example:
GET /fhir/R4/Observation?patient=12345&category=vital-signs&date=ge2023-01-01
Use _include, _revinclude, _count, and _elements to control the response content and size.
Custom Operations
Operations beginning with $ are invoked using POST or GET depending on the endpoint. These support advanced workflows such as full patient record retrieval or document exports.
Example:
POST /fhir/STU3/Patient/$p360-retrieve
Refer to the FHIR Operations documentation for usage and supported parameters.
Response Codes
FHIR interactions return standard HTTP status codes. Errors include an OperationOutcome resource with details.
| Code | Meaning |
|---|---|
| 200 | Success |
| 201 | Resource created |
| 202 | Request accepted (async job) |
| 400 | Invalid request or validation error |
| 401 | Unauthorized |
| 404 | Resource not found |
| 409 | Conflict (e.g., duplicate data) |
| 422 | Unable to process (payload issue) |
| 429 | Too many requests (rate limited) |
Review the response body for details when a request fails.
Behavior Notes
- All timestamps are returned in ISO 8601 UTC format.
- Null or empty fields are omitted from responses.
- Arrays (e.g., identifier, address) may contain one or more elements.
- Resource references use FHIR format (e.g., Patient/12345).