Changes API
Simple API to react on resource changes
Changes API can be used to get changes of resourceType or specific resource by versions. Each event (creating, updating, deleting) will increase version of the resource by 1.
Polling request is cheap! If you want to watch rare changes (minutes-hours), this API is very resource efficient (no subscriptions, no queues) and provides you lots of control. If nothing has been changed, you will get a response with status
304, otherwise Changes API will response with a list of changes and a new version to poll next time.GET /<resourceType>/$changes — returns the latest version for the resourceType.GET /<resourceType>/$changes?<parameters>— depending on parameters returns changes of the resourceType. GET /<resourceType>/<id>/$changes — returns latest version of a specific resource.GET /<resourceType>/<id>/$changes?<parameters>— depending on parameters returns changes of the specific resource. Below are parameters to use in both resourceType and specific resource endpoints.
Parameter | Meaning |
|---|---|
version=<version> | Returns changes since the specified version |
version=<lower-version>,<upper-version> | Returns changes after the lower-version (exclusive) up to theupper-version (inclusive) |
fhir=<boolean> | If set to true converts changes.*.resource to the FHIR format
(note: since Changes API is not /fhir/ endpoint, the rest of the body isn't FHIR compliant) |
omit-resources=<boolean> | If set to true omits resources leaving only id & resourceType fields |
_count & _page | |
_total & _totalMethod |
With parameters which start with dot you can filter resources by equality, e.g.
.name.0.family=<string>Get the latest version of the Patient resource.
GET /Patient/$changes
Accept: text/yaml
# status 200
version: 1
Assume the latest version is 1, no changes since version 1.
GET /Patient/$changes?version=1
Accept: text/yaml
# status 304 (Not Modified)
Let's add 2 patients to change version of Patient resource.
POST /Patient
Accept: text/yaml
Content-Type: text/yaml
id: pt-1
name:
- family: Smith
given: [John]
POST /Patient
Accept: text/yaml
Content-Type: text/yaml
id: pt-2
name:
- family: Wood
given: [Amanda]-a
Since version 1, two events happened: created 2 patients.
GET /Patient/$changes?version=1
Accept: text/yaml
# status 200
version: 3
changes:
- event: created
resource:
id: pt-1
name:
- family: Smith
given: [John]
- event: created
resource:
id: pt-2
name:
- family: Wood
given: [Amanda]
GET /Patient/$changes?version=1&.name.0.family=Wood
Accept: text/yaml
# status 200
version: 3
changes:
- event: created
resource:
id: pt-2
name:
- family: Wood
given: [Amanda]
Check changes happened since version 1 until version 2.
GET /Patient/$changes?version=1,2
Accept: text/yaml
# status 200
version: 2
changes:
- event: created
resource:
id: pt-1
name:
- family: Smith
given: [John]
Check version of patient with id
pt-1.GET /Patient/pt-1/$changes
Accept: text/yaml
# status 200
version: 2
GET /Patient/pt-1/$changes?version=1
Accept: text/yaml
# status 200
version: 2
changes:
- event: created
resource:
id: pt-1
name:
- family: Smith
given: [John]
Use
omit-resources=true to request only id and resourceType fields in resources.GET /Patient/$changes?version=1&omit-resources=true
Accept: text/yaml
# status 200
version: 3
changes:
- event: created
resource: {id: pt-1, resourceType: Patient}
- event: created
resource: {id: pt-2, resourceType: Patient}
Changes API uses a cache to track a resourceType last change. To build the cache it runs a query to get the
max value of the txid column. To make this operation efficient, it is recommended to build an index on the txid column for tables where Changes API will be used.Use query:
CREATE INDEX IF NOT EXISTS <resourceType>_txid_btree ON <resourceType> using btree(txid);
CREATE INDEX IF NOT EXISTS <resourceType>_history_txid_btree ON <resourceType>_history using btree(txid);
Replace <resourceType> with table name, for example:
CREATE INDEX IF NOT EXISTS patient_txid_btree ON patient using btree(txid);CREATE INDEX IF NOT EXISTS patient_history_txid_btree ON patient_history using btree(txid);Last modified 7mo ago