Table of Contents

Resources Endpoint

You can publish data into a dataset using the resources endpoint

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

where datasetId is the name of the dataset, for example plots.
In the above case the URL would look like:

POST https://api.purefarming.com/data/streaming/dataset/plots/resources

Request

Supply a list of objects that match the dataset specification. For example, for the plots dataset:

[
  {
    "totalArea": {
      "measurement": 2000,
      "units": "MTK"
    },
    "totalLength": {
      "measurement": 100,
      "units": "MTK"
    },
    "identifiers": [
      {
        "id": "79daf037-407e-49b0-b385-6cb5b9e5453c",
        "scheme": "com.purefarming.holdingId"
      },
      {
        "id": "12/123/1234",
        "scheme": "uk.defra.cph"
      }
    ],
    "meta": {
      "sourceId": {
        "scheme": "com.my-software.plotId",
        "id": "1398e88c-4521-4e82-9974-9ae5ff8fea4d"
      },
      "modified": "2024-01-24T01:16:30.9991950+00:00"
    },
    "name": "My Plot",
    "resourceType": "plotResource"
  }
]

See Supported Resource Types for a list of resource types the streaming API will accept.

Requirements

Each resource type will have some information that is required.
In most cases this is the meta, but it can and does vary by resource type.

For example:

{
  ...
  "meta": {
    "sourceId": {
      "id": "123",
      "scheme": "com.my-software.id"
    },
    "modified": "2024-01-24T01:16:30.9991950+00:00",
    "created": "2024-01-22T01:10:00.9991950+00:00"
  }
}

The meta in the above example tells Pure Farming what the ID of this item is in your system, which enables us to match the incoming record to any existing Pure Farming record to avoid data duplication

It is also important that where possible (and the resource type supports it) to provide information about where the record is located, i.e. the Pure Farming holding to which it belongs. This should take the form of the official or well known identifier for the holding. This is usually the same identifier supplied when creating a holding.

Usage Examples

The examples below show how to call the Streaming API and POST data to the resources endpoint.

Please note that the data included is example only, and will not work against the API as all values are fictional.

// get an HTTP client
var client = _httpClientFactory.Get();

// get the object as JSON
var plotJson = "[{\"totalArea\":{\"measurement\":2000,\"units\":\"MTK\"},\"totalLength\":{\"measurement\":100,\"units\":\"MTK\"},\"identifiers\":[{\"id\":\"79daf037-407e-49b0-b385-6cb5b9e5453c\",\"scheme\":\"com.purefarming.holdingId\"},{\"id\":\"12/123/1234\",\"scheme\":\"uk.defra.cph\"}],\"meta\":{\"sourceId\":{\"scheme\":\"com.my-software.plotId\",\"id\":\"1398e88c-4521-4e82-9974-9ae5ff8fea4d\"},\"modified\":\"2024-01-24T01:16:30.9991950+00:00\"},\"name\":\"MyPlot\",\"resourceType\":\"plotResource\"}]";

// set the bearer token
client.DefaultHeaders.Authorization = new AuthenticationHeaderValue("Bearer", _token);

// create content and post
var stringContent = new StringContent(plotJson);
var response = await client.PostAsync("https://api.purefarming.com/data/streaming/dataset/plots/resources", stringContent);

Response

A response from the resources endpoint tells you if inserting the data into Pure Farming succeeded or failed. The response is an array of items providing the status of each original item pushed.

[
  {
    "successful": true,
    "index": 0
  },
  {
    "successful": false,
    "index": 1,
    "error": "Could not find Holding for: \"com.purefarming.holdingId\":\"79daf037-407e-49b0-b385-6cb5b9e5453c\""
  },
  ...
]
Response Item Description Data Type
Successful Whether the item at position index was successfully queued for processing in Pure Farming Boolean
Index The zero-indexed position of the object in the incoming list that was sent Integer
Error An error message if the object could not be queued for processing in Pure Farming String