improved

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 a 202 HTTP response code.
  • PERSISTED indicates that the request is completed and the data has been persisted. This returns a 201 HTTP response code when a record is created and 200 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