Streaming API

Introduction

Pure Farming's Streaming API defines a protocol for how a client can consume data from a server and update a local database or store; or push data to a remote endpoint and modify a collection of resources.

We expose a number of datasets (resource types). Each dataset contains resources of one or more type and exposes a feed of changes. Each change is represented as the latest representation of a resource that has been created, modified or deleted. Each resource has unique identity across all resources in all datasets. This is known as the data point key.

It is based off the Mimiro Universal Data API standard which you can find here: https://open.mimiro.io/specifications/uda/latest.html#api

The PureFarming Streaming API has two notable differences from the Mimiro standard:

1. The addition of a control endpoint
2. The entities endpoint has been renamed to resources endpoint

Motivation

The main motivation of this API is to enable the synchronisation of Pure Farming resources between our system and yours in a generalised manner and without you needing to be timezone aware.

Because the API is generic and not bound by resource type the Streaming API lets us, on the Pure Farming side, add more resource type capability without publishing new versions of the API.

The API is designed to be super simple and bring a low bar of entry to any software to enable it to participate in a data sharing eco-system. There are just 4 endpoints defined in this API yet that is enough to enable the exchange of any Pure Farming resource.

Protocol Definition

The Streaming API has a single entry point and is consistently structured to allow introspection and dynamic navigation. The following endpoints are exposed:

Name	Method	URI
Control	GET	/data/streaming/control
Datasets	GET	/data/streaming/datasets
	GET	/data/streaming/datasets/{dataset}
Changes	GET	/data/streaming/datasets/{dataset}/changes
Resources	POST	/data/streaming/datasets/{dataset}/resources

Note: Where {dataset} is specified, this is the name of the dataset as returned by the datasets URL.

For more information on the base URLs for each environment, see the enviroments page.

Endpoints

Control Endpoint

The Control endpoint allows you to see which holdings and which resource types you are allowed to publish data for using the Resources endpoint.

GET /data/streaming/control

See further information in the Control Endpoint page

Datasets Endpoint

The dataset endpoints give you up-to-date information about what datasets (resource types) the API supports.

GET /data/streaming/datasets
GET /data/streaming/datasets/{dataset}

See further information in the Dataset Endpoints page

Changes Endpoint

Gets the latest version of all resources of a particular dataset. You can specify a continuation token which will only return resources that have changed since the last time you called the API.

GET /data/streaming/datasets/{dataset}/changes

See further information about the endpoint and continuation token in the Changes Endpoint page

Resources Endpoint

Publishes new data or updates to existing data for a dataset. This allows you to publish large streams of data into the Pure Farming platform.

POST /data/streaming/datasets/{dataset}/resources

See further information in the Resources Endpoint page