Read the current state of the resource
The interaction is performed by an HTTP GET command as shown:
GET [base]/[type]/[id] {?_format=[mime-type]}
FHIR Reference: https://hl7.org/fhir/http.html#read
Example usage:
const patient = await client.read<Patient>({
type: "Patient",
id: "patient-id",
});
Read the state of a specific version of the resource
The interaction is performed by an HTTP GET command as shown:
GET [base]/[type]/[id]/_history/[vid] {?_format=[mime-type]}
FHIR Reference: https://hl7.org/fhir/http.html#vread
Example usage:
const patient = await client.vread<Patient>({
type: "Patient",
id: "patient-id",
vid: "version-id",
});
Update an existing resource by its id (or create it if it is new)
The update interaction is performed by an HTTP PUT command as shown:
PUT [base]/[type]/[id] {?_format=[mime-type]}
FHIR Reference: https://hl7.org/fhir/http.html#update
Example usage:
const result = await client.update<Patient>({
type: "Patient",
id: patientId,
resource: {
resourceType: "Patient",
name: [{
family: "Smith",
given: ["John"],
}],
},
});
Conditional Update allows a client to update an existing resource based on some identification criteria, rather than by logical id.
The conditional update interaction is performed by an HTTP PUT command as shown:
PUT [base]/[type]?[search parameters]
FHIR Reference: https://hl7.org/fhir/http.html#cond-update
Update an existing resource by posting a set of changes to it.
The patch interaction is performed by an HTTP PATCH command as shown:
PATCH [base]/[type]/[id] {?_format=[mime-type]}
The body of a PATCH interaction is a JSON Patch icon document with a content type of application/json-patch+json.
FHIR Reference: https://hl7.org/fhir/http.html#patch
Conditional Patch performs a search using the standard search facilities for the resource type, with the goal of resolving a single logical id for this request. The action it takes depends on how many matches are found.
The conditional patch interaction is performed by an HTTP PATCH command as shown:
PATCH [base]/[type]?param1=value&...{&_format=[mime-type]}
The body of a PATCH interaction is a JSON Patch icon document with a content type of application/json-patch+json.
FHIR Reference: https://hl7.org/fhir/http.html#cond-patch
Delete a resource.
The interaction is performed by an HTTP DELETE command as shown:
DELETE [base]/[type]/[id]
FHIR Reference: https://hl7.org/fhir/http.html#delete
Example usage:
const patient = await client.delete<Patient>({
type: "Patient",
id: "patient-id",
});
Delete all historical versions of a resource.
The interaction is performed by an HTTP DELETE command as shown:
DELETE [base]/[type]/[id]/_history
FHIR Reference: https://build.fhir.org/http.html#delete-history
Delete a specific version of a resource.
The interaction is performed by an HTTP DELETE command as shown:
DELETE [base]/[type]/[id]/_history/[vid]
FHIR Reference: https://build.fhir.org/http.html#delete-history-version
Retrieve the change history for a particular resource.
The interaction is performed by an HTTP GET command as shown:
GET [base]/[type]/[id]/_history{?[parameters]&_format=[mime-type]}
FHIR Reference: https://hl7.org/fhir/http.html#history
Search the resource type based on some filter criteria.
The interaction is performed by an HTTP GET command as shown:
GET [base]/[resource-type]/?param1=value&...{&_format=[mime-type]}
FHIR Reference: https://hl7.org/fhir/http.html#search-get
Example usage:
const searchset: Bundle = await client.searchType({
type: "Patient",
query: [["family", "Unknown"]],
});
Create a new resource with a server assigned id.
The create interaction is performed by an HTTP POST command as shown:
POST [base]/[type] {?_format=[mime-type]}
FHIR Reference: https://hl7.org/fhir/http.html#create
Example usage:
const patient = await client.create<Patient>({
type: "Patient",
resource: {
id: "patient-id",
name: [{
family: "Test",
given: ["Patient"],
}],
},
});
The conditional create interaction allows a client to create a new resource only if some equivalent resource does not already exist on the server.
The client defines what equivalence means in this case by supplying a FHIR search query using an HL7 defined extension header If-None-Exist.
The conditional create interaction is performed by an HTTP POST command as shown:
POST [base]/[type]?param1=value&...{&_format=[mime-type]}
FHIR Reference: https://hl7.org/fhir/http.html#ccreate
Conditional Delete across all resource types based on some filter criteria
If type is provided, performs conditional delete across a particular resource type based on some filter criteria.
To accomplish this, the client issues an HTTP DELETE as shown:
DELETE [base]/[type]?[search parameters]
DELETE [base]?[search parameters]
FHIR Reference: https://hl7.org/fhir/http.html#cdelete
Retrieve the change history for all resources.
The interaction is performed by an HTTP GET command as shown:
GET [base]/_history{?[parameters]&_format=[mime-type]}
FHIR Reference: https://hl7.org/fhir/http.html#history
Search the system based on some filter criteria.
The interaction is performed by an HTTP GET command as shown:
GET [base]?param1=value&...{&_format=[mime-type]}
FHIR Reference: https://hl7.org/fhir/http.html#search-get
Example usage:
const searchset: Bundle = await client.searchSystem({
query: [["family", "Unknown"]]
});
Conditional Delete across all resource types based on some filter criteria
If type is provided, performs conditional delete across a particular resource type based on some filter criteria.
To accomplish this, the client issues an HTTP DELETE as shown:
DELETE [base]/[type]?[search parameters]
DELETE [base]?[search parameters]
FHIR Reference: https://hl7.org/fhir/http.html#cdelete
Retrieve the change history for a particular resource type.
The interaction is performed by an HTTP GET command as shown:
GET [base]/[type]/_history{?[parameters]&_format=[mime-type]}
FHIR Reference: https://hl7.org/fhir/http.html#history
Get a capability statement for the system.
The interaction is performed by an HTTP GET command as shown:
GET [base]/metadata{?mode=[mode]} {&_format=[mime-type]}
The mode can be:
| Mode | Description |
|---|---|
full |
A CapabilityStatement that specifies which resource types and interactions are supported |
normative |
As above, but only the normative portions of the Capability Statement |
terminology |
A TerminologyCapabilities resource that provides further information about terminologies which are supported by the server |
FHIR Reference: https://hl7.org/fhir/http.html#capabilities
Perform multiple operations in a batch request (e.g. create, read, update, delete, patch, and/or [extended operations])
A batch interaction is performed by an HTTP POST command as shown:
POST [base] {?_format=[mime-type]}
FHIR Reference: https://hl7.org/fhir/http.html#transaction
Perform multiple operations as a transaction (e.g. create, read, update, delete, patch, and/or [extended operations])
A transaction interaction is performed by an HTTP POST command as shown:
POST [base] {?_format=[mime-type]}
FHIR Reference: https://hl7.org/fhir/http.html#transaction
Search the resource type across the compartment based on some filter criteria.
The interaction is performed by an HTTP GET command as shown:
GET [base]/[compartment-type]/[compartment-id]/[resource-type]?param1=value&...{&_format=[mime-type]}
FHIR Reference: https://hl7.org/fhir/http.html#search-get
Example usage:
const result: Bundle = await client.searchCompartment({
compartment: "Patient",
compartmentId: "patient-id",
type: "Observation",
query: [["status", "final"]],
});
Perform an operation as defined by an OperationDefinition.
The interaction is performed by an HTTP POST command as shown:
POST [base]/[type]/[operation] {?_format=[mime-type]}
POST [base]/[type]/[id]/[operation] {?_format=[mime-type]}
FHIR Reference: https://hl7.org/fhir/operations.html
Perform the Validate Operation.
The interaction is performed by an HTTP POST command as shown:
[base]/[type]/$validate
[base]/[type]/[id]/$validate
FHIR Reference: https://hl7.org/fhir/operation-resource-validate.html
Execute a raw SQL query against the Aidbox database.
The interaction is performed by an HTTP POST command as shown:
POST [base]/$sql
Example usage:
Important: Always use parameterized queries to prevent SQL injection.
Pass user-supplied values via params, never interpolate them into the query string.
// Good — parameterized
const result = await client.sql<{ cnt: number }>(
"SELECT count(*) as cnt FROM patient WHERE id = ?", [patientId]
);
// Bad — SQL injection risk
const result = await client.sql(`SELECT * FROM patient WHERE id = '${patientId}'`);
Note: $sql is an Aidbox-specific endpoint (not part of the FHIR spec).
The URL uses the Aidbox-native prefix (/$sql), not the FHIR prefix (/fhir/$sql).
Optionalparams: (string | number | boolean | null)[]Materialize a ViewDefinition into a flat table.
The interaction is performed by an HTTP POST command as shown:
POST [base]/fhir/ViewDefinition/[id]/$materialize
Example usage:
const result = await client.materialize("view-def-id", "materialized-view");
Performs a request to /auth/userinfo.
Performs a request to /auth/logout.
Typed request
Example usage:
const result = client.request<Patient>({
method: "GET",
url: "/fhir/Patient/pt-1",
})
if (isOk(result)) {
const { value } = result;
// work with value as a Patient type
} else {
const { error } = result;
// work with error as an OperationOutcome type.
}
Untyped request.
Example usage:
const result = client.rawRequest({
method: "GET",
url: "/fhir/Patient/pt-1",
})
Obtain server's base URL.
Create a client to the FHIR server.
Main client functions are
requestfor typed interactions, andrawRequestfor manual response processing.This client also provides a set of convenience methods for accessing FHIR operations, provided below.