Change feed overview

The change feed provides logs of all the changes that occur in the DICOM® service. The change feed provides ordered, guaranteed, immutable, and read-only logs of these changes. The change feed offers the ability to go through the history of DICOM service and acts upon the creates, updates, and deletes in the service.

Client applications can read these logs at any time in batches of any size. The change feed enables you to build efficient and scalable solutions that process change events that occur in your DICOM service.

You can process these change events asynchronously, incrementally or in-full. Any number of client applications can independently read the change feed, in parallel, and at their own pace.

As of v2 of the API, the change feed can be queried for a particular time window.

Make sure to specify the version as part of the URL when making requests. More information can be found in the API Versioning for DICOM service Documentation.

API Design

The API exposes two GET endpoints for interacting with the change feed. A typical flow for consuming the change feed is provided in the Usage section.

Verb	Route	Returns	Description
GET	/changefeed	JSON Array	Read the change feed
GET	/changefeed/latest	JSON Object	Read the latest entry in the change feed

Object model

Field	Type	Description
Sequence	long	The unique ID per change event
StudyInstanceUid	string	The study instance UID
SeriesInstanceUid	string	The series instance UID
SopInstanceUid	string	The sop instance UID
Action	string	The action that was performed - either create, update, or delete
Timestamp	datetime	The date and time the action was performed in UTC
State	string	The current state of the metadata
Metadata	object	Optionally, the current DICOM metadata if the instance exists

States

State	Description
current	This instance is the current version.
replaced	This instance is replaced with a new version.
deleted	This instance is deleted and is no longer available in the service.

Change feed

The change feed resource is a collection of events that occurred within the DICOM server.

Version 2

Request

GET /changefeed?startTime={datetime}&endtime={datetime}&offset={int}&limit={int}&includemetadata={bool} HTTP/1.1
Accept: application/json
Content-Type: application/json

Response

[
    {
        "Sequence": 1,
        "StudyInstanceUid": "{uid}",
        "SeriesInstanceUid": "{uid}",
        "SopInstanceUid": "{uid}",
        "Action": "create|delete",
        "Timestamp": "2020-03-04T01:03:08.4834Z",
        "State": "current|replaced|deleted",
        "Metadata": {
            // DICOM JSON
        }
    },
    {
        "Sequence": 2,
        "StudyInstanceUid": "{uid}",
        "SeriesInstanceUid": "{uid}",
        "SopInstanceUid": "{uid}",
        "Action": "create|delete",
        "Timestamp": "2020-03-05T07:13:16.4834Z",
        "State": "current|replaced|deleted",
        "Metadata": {
            // DICOM JSON
        }
    },
    //...
]

Parameters

Name	Type	Description	Default	Min	Max
offset	long	The number of events to skip from the beginning of the result set	0	0
limit	int	The maximum number of events to return	100	1	200
startTime	DateTime	The inclusive start time for change events	"0001-01-01T00:00:00Z"	"0001-01-01T00:00:00Z"	"9999-12-31T23:59:59.9999998Z"
endTime	DateTime	The exclusive end time for change events	"9999-12-31T23:59:59.9999999Z"	"0001-01-01T00:00:00.0000001"	"9999-12-31T23:59:59.9999999Z"
includeMetadata	bool	Indicates whether or not to include the DICOM metadata	true

Version 1

Request

GET /changefeed?offset={int}&limit={int}&includemetadata={bool} HTTP/1.1
Accept: application/json
Content-Type: application/json

Response

[
    {
        "Sequence": 1,
        "StudyInstanceUid": "{uid}",
        "SeriesInstanceUid": "{uid}",
        "SopInstanceUid": "{uid}",
        "Action": "create|delete",
        "Timestamp": "2020-03-04T01:03:08.4834Z",
        "State": "current|replaced|deleted",
        "Metadata": {
            // DICOM JSON
        }
    },
    {
        "Sequence": 2,
        "StudyInstanceUid": "{uid}",
        "SeriesInstanceUid": "{uid}",
        "SopInstanceUid": "{uid}",
        "Action": "create|delete",
        "Timestamp": "2020-03-05T07:13:16.4834Z",
        "State": "current|replaced|deleted",
        "Metadata": {
            // DICOM JSON
        }
    },
    // ...
]

Parameters

Name	Type	Description	Default	Min	Max
offset	long	The exclusive starting sequence number for events	0	0
limit	int	The maximum value of the sequence number relative to the offset. For example, if the offset is 10 and the limit is 5, then the maximum sequence number returned is 15.	10	1	100
includeMetadata	bool	Indicates whether or not to include the DICOM metadata	true

Latest change feed

The latest change feed resource represents the latest event that occurred within the DICOM server.

Request

GET /changefeed/latest?includemetadata={bool} HTTP/1.1
Accept: application/json
Content-Type: application/json

Response

{
    "Sequence": 2,
    "StudyInstanceUid": "{uid}",
    "SeriesInstanceUid": "{uid}",
    "SopInstanceUid": "{uid}",
    "Action": "create|update|delete",
    "Timestamp": "2020-03-05T07:13:16.4834Z",
    "State": "current|replaced|deleted",
    "Metadata": {
        //DICOM JSON
    }
}

Parameters

Name	Type	Description	Default
includeMetadata	bool	Indicates whether or not to include the metadata	true

Usage

User application

Version 2

1. An application regularly queries the change feed on some time interval
   • For example, if querying every hour, a query for the change feed might look like /changefeed?startTime=2023-05-10T16:00:00Z&endTime=2023-05-10T17:00:00Z
   • If starting from the beginning, the change feed query might omit the startTime to read all of the changes up to, but excluding, the endTime
     • For example: /changefeed?endTime=2023-05-10T17:00:00Z
2. Based on the limit (if provided), an application continues to query for more pages of change events if the number of returned events is equal to the limit (or default) by updating the offset on each subsequent query
   • For example, if the limit is 100, and 100 events are returned, then the subsequent query would include offset=100 to fetch the next "page" of results. The queries demonstrate the pattern:
     • /changefeed?offset=0&limit=100&startTime=2023-05-10T16:00:00Z&endTime=2023-05-10T17:00:00Z
     • /changefeed?offset=100&limit=100&startTime=2023-05-10T16:00:00Z&endTime=2023-05-10T17:00:00Z
     • /changefeed?offset=200&limit=100&startTime=2023-05-10T16:00:00Z&endTime=2023-05-10T17:00:00Z
   • If fewer events than the limit are returned, then the application can assume that there are no more results within the time range

Version 1

1. An application determines from which sequence number it wishes to start reading change events:
   • To start from the first event, the application should use offset=0
   • To start from the latest event, the application should specify the offset parameter with the value of Sequence from the latest change event using the /changefeed/latest resource
2. On some regular polling interval, the application performs the following actions:
   • Fetches the latest sequence number from the /changefeed/latest endpoint
   • Fetches the next set of changes for processing by querying the change feed with the current offset
     • For example, if the application processed up to sequence number 15 and it only wants to process at most five events at once, then it should use the URL /changefeed?offset=15&limit=5
   • Processes any entries return by the /changefeed resource
   • Updates its current sequence number to either:
     1. The maximum sequence number returned by the /changefeed resource
     2. The offset + limit if no change events were returned from the /changefeed resource, but the latest sequence number returned by /changefeed/latest is greater than the current sequence number used for offset

Other potential usage patterns

Change feed support is well-suited for scenarios that process data based on objects that are changed. For example, it can be used to:

• Build connected application pipelines like ML that react to change events or schedule executions based on created or deleted instance.
• Extract business analytics insights and metrics, based on changes that occur to your objects.
• Poll the change feed to create an event source for push notifications.

Next steps

Pull changes from the change feed

Note

DICOM® is the registered trademark of the National Electrical Manufacturers Association for its Standards publications relating to digital communications of medical information.