Changes Endpoint

The changes endpoint for a dataset returns the latest version of any item that has changed.
The response from this request is an array of JSON objects. The first object is a context that is reserved for future use. The last object is a continuation object that allows clients to consume subsequent changes.

Warning

At present there is one scenario where data will not be returned from the Changes endpoint. When a holding grants you access to their data, data that existed prior to granting access will not be returned through the Streaming API.

You can get around this by:

Polling the Ecosystem APIs /self/holdings endpoint
Checking for new holdings that were added (compare this to the previous time you called the /self/holdings endpoint)
Call the Data APIs /holdings/{holdingId}/{resourceType} endpoints to get all existing data for that holding
After this you can continue to call the Changes endpoint and it will return new or updated data for the holding you were granted access to

Any data put against (or updated on) the holding after you have been granted access will come through the Streaming API

Overview

GET /data/streaming/datasets/{datasetid}/changes?since={sinceToken}

The changes endpoint returns the following JSON response:

[
  {
    "id": "@context",
    "description": "application specific / expansion point for rdf, JSON-LD and Entity Graph Data Model"
  },
  {
    "resourceType": "holdingResource",
    "name": "Holding1",
    "id": "4dd345e8-c91b-4bf2-a102-a9f86b01c46b"
  },
  {
    "resourceType": "holdingResource",
    "name": "Holding2",
    "id": "ef5beba4-ed61-43af-b258-026a45062b95"
  },
  {
    "id": "@continuation",
    "token": "token-issued-by-server-to-get-more-data"
  }
]

Response Breakdown

The response has three parts to it:

The @context
The items
The @continuation token

@context

The first object in the response is for future use and will contain context information. Likely uses are for JSON-LD, or the Entity Graph Data Model.

The items

The main set of objects in the response are Pure Farming resources. There can be 0 or more resources.

For example, the following response is valid:

GET /data/streaming/datasets/holdings/changes?since={sinceToken}

[
  {
    "id": "@context",
    "description": "application specific / expansion point for rdf, JSON-LD and Entity Graph Data Model"
  },
  {
    "id": "@continuation",
    "token": "xxyyzz"
  }
]

The above response indicates there were no changes to any plots since the last time the API was called (indicated by the ?since={sinceToken}). When a client receives the Pure Farming resources it must process them in order.
For each entity it must do the following:

Check if the meta/isDeleted flag is set to true If so, the local resource with the corresponding id must be deleted or marked as deleted.
If there is no local version of the resource it must be created and the id must be associated with the local object in some way
If there is a local object with the correlating id then this representation must be deleted and replaced with the one received Implementations are free to perform deltas, but the result must be the same

@continuation token

The last object in the array is a continuation token and contains a property token. The token is an object encoded with base64. This token is issued by the server and clients must not manipulate the contents. Manipulating the contents of a continuation token gives undefined behaviour when used as part of a subsequent request.

A client is responsible for storing the continuation token and then using it as the since token in subsequent calls. e.g.

GET /data/streaming/datasets/{datasetid}/changes?since=token-issued-by-server-to-get-more-data

Note that the continuation token can be used by the server to provide paging. A client typically calls to the changes endpoint until no resources are returned. It then stores the token and then waits for some period before asking again.

Note: The definition of "no resources", is that the response only contains the @context and @continuation items.

The client should only store the contiuation token if it has succesfully processed all resources returned in a response.

Table of Contents