API Guides

Introduction

Pure Farming provides many APIs to make the job of integration easier. The most commonly used ones are:

Tip

To see more information about our environments, visit Environments for more information. Each of the above APIs are available in all our environments although not all endpoints may be supported in the Production and Demo environments.

We also recommend looking at the following topics:

If you are ready to start exploring the APIs and want to come back to the guides later, take a look at our API Explorer.

How we use JSON

All Pure Farming APIs return data using JSON. If you attempt to request data using another format (e.g. XML), you will still be returned JSON.
Each object which is returned from our APIs is described independently using JSON Schema. This allows you to validate the structure of the response objects and understand the expected properties. For more information on how we use JSON Schema, see Schema.

For more information on JSON itself, see the ECMA-404 standard.

Pure Farming's JSON responses conform to industry best practice both as part of the JSON specification, but also in terms of structure and content.
This means that responses will not include properties which are not present in the data being returned, specifically if they are not required as part of the schema definition.

API Responses

For example, using the icarAnimalCoreResource:

The only required properties are:
- identifier
- specie
- gender

All other properties are optional. So if those properties are not present in the received data, they will not be included in the JSON response. This helps keep responses lean, focused and easy to consume.

A minimal example for icarAnimalCoreResource would be:

{
  "resourceType": "icarAnimalCoreResource",
  "identifer": {
    "scheme": "uk.cts.eartag",
    "id": "UK123456701172"
  },
  "specie": "Cattle",
  "gender": "MaleNeuter"
}

Note

You will notice that only the properties that are required by the schema definition are included in the response. This not only minimises the size of the response, but also makes it very clear what data is actually present versus what may have just been omitted.

A slightly more full example for an icarAnimalCoreResource may include some optional properties:

{
  "resourceType": "icarAnimalCoreResource",
  "identifier": {
    "scheme": "uk.cts.eartag",
    "id": "UK123456701172"
  },
  "location": {
    "scheme": "uk.cph",
    "id": "08/675/0020"
  },
  "specie": "Cattle",
  "gender": "Male",
  "birthDate": "2022-06-26T00:00:00Z",
  "primaryBreed": {
    "scheme": "uk.cts.breed",
    "id": "HF"
  },
  "parentage": [
    {
      "parentOf": {
        "id": "UK123456701172",
        "scheme": "uk.cts.eartag"
      },
      "gender": "Female",
      "relation": "Genetic",
      "identifier": {
        "id": "UK123456700927",
        "scheme": "uk.cts.eartag"
      }
    }
  ]
}

Again you will note that only properties which have data are included, properties for which null is valid and actually have a meaning will be returned where appropriate.

Parsing JSON Responses

When parsing responses it is important to:

Ensure that you are doing so with reference to the appropriate schema for the object
Where possible using objects (if you are serializing and de-serializing from objects) which have been created using code generation from the schemas. This ensures the correct structure and types are used and dramatically reduces the likelihood of parsing errors.
Checking for presence or absence of properties as you go.
Note: This is often taken care of by your JSON parsing library but it's good practice to be aware of.
Handling null values appropriately. Many properties can accept null as a valid value if no data is available, however if you are using generated objects then this should be taken care of by your JSON parser.

Example

If you have used Code Generation (as described here) to create objects from our schemas then parsing responses becomes very straightforward:

.NET

var baseUrl = "https://api.purefarming.com/data";
var client = new LivestockApi(baseUrl);

var page = await client.GETDataLivestockAnimalsAsync(animalIdentifierScheme: "uk.cts.eartag");
var results = page.Items;

In the above example, you don't need to worry about the serialization/de-serialization of the objects and whether they match the schema - that is handled automatically by the generated code. You also don't need to check for null values as they will be handled appropriately.
The objects that are created using the code generation are generated according to the schema, so they will be marked as optional (nullable - language dependent) and serialized appropriately.

The main thing to keep in mind when using code generation for this is to ensure that your generated code stays up to date - this could be as simple as including it as a pre-build step in your build process, or as part of your CI/CD pipeline.

We endeavour to ensure that changes we make to the API are non-breaking, and that if there are any we will communicate these changes prior to deploying to production.

Table of Contents