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.
Additional Information
For Geospatial resource types the coordinates provided in centroid and spatialFeature will need to be provided in [(Longitudea, Latitude)].
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 |