Aidbox
Search…
Changes API
Simple API to react on resource changes
By GET /<resource-type>/$changes without the version parameter you will get latest version, which can be used to poll for changes by GET /<resource-type>/$changes?version=<version>

GET /<resourceType>/$changes returns the latest version for the resourceType GET /<resourceType>/<id>/$changes returns latest version of a specific resource Returned version value can be used with the version query-string parameter

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)
With parameters which start with dot you can filter resources by equality, e.g. .name.0.family=<string>
omit-resources=<boolean> if set to true omits resources leaving only id & resourceType fields
_count & _page work as described here _total & _totalMethod work as described here​

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 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);

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 a list of changes and a new version to poll next time.

---
GET /Patient/$changes
Accept: text/yaml
​
# status 200
version: 1
​
---
GET /Patient/$changes?version=1
Accept: text/yaml
​
# status 304 (Not Modified)
​
---
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]
​
---
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]
---
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]
---
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]
---
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}
Copy link
Edit on GitHub
On this page
Endpoints
Query-string parameters
Cache performance
Notes
Examples