Behaviour change for Registry APIs
Registry APIs now support asynchronous processing with status indicators and global task IDs for workflows.
Breaking Changes
New status for registry operations
The behaviour of the Registry APIs has changed to support asynchronous processes. The response payload for all POST, PUT and DELETE
endpoints will now include a status property. Depending on the status of the operation, a different response code will be returned.
{
status: 'ACCEPTED' | 'PERSISTED'
...aditional metadata
}
ACCEPTED
indicates that the request was captured and an asynchronous workflow has started. This returns a202
HTTP response code.PERSISTED
indicates that the request is completed and the data has been persisted. This returns a201
HTTP response code when a record is created and200
when a record has been updated or deleted.
The following Registry endpoints have been affected by this change:
POST | /sources/{sourceKey}/v1/resources/{resourceType} |
---|---|
PUT | /sources/{sourceKey}/v1/resources/{resourceType}/{id} |
DELETE | /sources/{sourceKey}/v1/resources/{resourceType}/{id} |
POST | /sources/{sourceKey}/v1/relationships/{relationshipType} |
PATCH | /sources/{sourceKey}/v1/relationships/{relationshipType}/{id} |
DELETE | /sources/{sourceKey}/v1/relationships/{relationshipType}/{id} |
PUT | /sources/{sourceKey}/v1/resources/{resourceType}/{id}/{nestedContainsPath} |
POST | /sources/{sourceKey}/v1/resources/{resourceType}/{id}/{nestedContainsPath} |
DELETE | /sources/{sourceKey}/v1/resources/{resourceType}/{id}/{nestedContainsPath} |
The bulk, bundle and purge endpoints will now return a taskId
property in addition to their workflow IDs. The IDs will be identical. bulkId
and purgeId
properties are planned to be deprecated in future versions, so you should migrate to using the taskId
property whenever possible. For now, both the bulkId
and purgeId
will live side-by-side with a global taskId
.
// IDs are the same
{
"status": "ACCEPTED"
"taskId": "2wPrtiDmeQL9TUD0dymXAjQZayG",
"bulkId": "2wPrtiDmeQL9TUD0dymXAjQZayG"
...
}
New payload for single registry operations
When creating, upserting or updating a single resource or relationship, the record data is now nested within a resource
object in the response payload instead of being at the root-level.
// Previous response payload
{
"data": {},
"id": "abc",
"meta": {}
}
// Current response payload
{
"resource": {
"data": {},
"id": "abc",
"meta": {}
},
"status": "PERSISTED"
}
Updated format for partition record source identifiers
A partition record often contains source identifiers in the meta.identifier
section, pointing back to the source records that make it up. The previous convention for those identifiers was the following:
// Convention
{
"identifier": [
{
"system": "{sourceKey}",
"value": "{sourceId}",
"use": "source"
}
]
}
// Example
{
"identifier": [
{
"system": "source-a",
"value": "1234567890",
"use": "source"
}
]
}
The source identifier convention has been updated to provide more information about the source record type. The new expected format is:
// Convention
{
"identifier": [
{
"system": "source",
"value": "{sourceId}",
"use": "{sourceKey}.{sourceRecordType}"
}
]
}
// Example
{
"identifier": [
{
"system": "source",
"value": "1234567890",
"use": "source-a.organization"
}
]
}
Updated format for relationship primary ID and partition relationship source identifiers
Source and Partition Relationship ID
A source or partition relationship has a primary ID, located in the id
property of a relationship. The previous convention accepted multiple formats for this ID, and they were the following:
// Long format
{
"id": "{fromRecordType}.{fromRecordID},{toRecordType}.{toRecordID}"
}
// Short format
{
"id": "{fromRecordID},{toRecordID}"
}
// Examples
{
"id": "organization.2wPrtnv8YwsKGNUZsyZXqpLGG3Q,practitioner.2wPrtnB5DJn715LTCIULiLgg3Mx"
}
{
"id": "2wPrtnv8YwsKGNUZsyZXqpLGG3Q,2wPrtnB5DJn715LTCIULiLgg3Mx"
}
The relationship ID convention has been updated to eliminate inconsistencies with relationship ID pattern across the whole system. The new expected format is:
// Convention
{
"id": "{fromRecordID}.{toRecordID}",
}
// Example
{
"id": "2wPrtnv8YwsKGNUZsyZXqpLGG3Q.2wPrtnB5DJn715LTCIULiLgg3Mx",
}
In the source, the fromRecordID
and toRecordID
are the source record IDs of the from
and to
source records for this relationship. In the partitions, they are be unified record IDs of the from
and to
unified records for the relationship.
Partition Relationship Source Identifiers
A partition relationship often contains source identifiers in the meta.identifier
section, pointing back to the source relationships that make it up. The previous convention for those identifiers was the following:
// Convention
{
"identifier": [
{
"system": "{sourceKey}",
"value": "{sourceRelationshipType}:{fromSourceRecordID},{toSourceRecordID}",
"use": "source"
}
]
}
// Example
{
"identifier": [
{
"system": "source-a",
"value": "organition-practitioner:2wPrtnv8YwsKGNUZsyZXqpLGG3Q,2wPrtnB5DJn715LTCIULiLgg3Mx",
"use": "source"
}
]
}
The source identifier convention has been updated to eliminate inconsistencies with relationship ID pattern across the whole system. The new expected format is:
// Convention
{
"identifier": [
{
"system": "source",
"value": "{fromSourceRecordID}.{toSourceRecordID}",
"use": "{sourceKey}.{sourceRelationshipType}"
}
]
}
// Example
{
"identifier": [
{
"system": "source",
"value": "2wPrtnv8YwsKGNUZsyZXqpLGG3Q.2wPrtnB5DJn715LTCIULiLgg3Mx",
"use": "source-a.organization-practitioner"
}
]
}
Features
- Adds option to use clinia models in the ingestion pipeline for chunking and embedding data
Improvements
- Improvements in propagation performance of relationships from source to MDM to partitions.
- Improved search performance for data partitions with better indexing
- Clearer error messages for purge operations
- Improve the consistency of relationship identifiers in GET endpoints and query filters