Integration Guide

Pure Farming has many different endpoints and ways that you can integrate with it. Please have a read through our recommended approach below.

Ways to Integrate

There are three main ways to integrate with Pure Farming:

Using the Data API - This is the recommended approach for some integrations. The Data API provides a RESTful interface to access and modify agricultural data.
Using the Streaming API - For integrations that only want to receive changes, the Streaming API provides data streams that can be subscribed to.
Using Webhooks - For some integrations, webhooks provide an event-driven approach where Pure Farming will call your system when certain events occur.

Each of the above integration methods have their own pros and cons, as detailed in the below table.

Method	Pros	Cons
Data API	- Full control over data fetching and modifying	- Requires more development effort
	- Simple to implement	- More API calls
		- Harder to find the endpoints you need

Streaming API	- Receive data changes simply	- Limited control over how data is returned
	- Lower API call volume	- Harder to parse response stream
	- Easy to identify the resource types you want

Webhooks	- Simple event-driven integration	- Limited control over data returned
	- No polling required	- Reliability depends on Pure Farming's ability to deliver webhook messages
	- Subscription based

Recommended Approach

We recommend that most integrations use the Streaming API, this provides a good balance between:

Number of API calls and difficulty to implement
Control over the data you receive
Simplicity of an event-driven approach

In addition to this, the combination of the Streaming API with webhooks provides the best of both worlds.
This allows you to receive notifications of changes as they occur, as well as filling any gaps in the data you receive using the Streaming API on a more scheduled basis.

The below diagram shows how a client can interact with both the Streaming API and webhooks:

%%{init: {'theme':'neutral'}}%%
flowchart LR
  in(Data)
  pf(((Pure Farming)))
  in-->|into|pf
  c(Client)
  pf-..->|webhooks push to|c
  c-->|requests from Streaming API|pf

For more information on how to configure webhooks for your use case see the Webhooks Guide for more info.

Language Interoperability and API Client Generation

We recommend that you use client generation to create client libraries that interact with the Pure Farming APIs. This will wrap all of the complexity of connecting to the Pure Farming APIs into a library, so you can focus on writing code for your application.

All of our APIs provide OpenAPI specifications and are able to have client libraries generated for them.
The tool that we recommend to do this is: OpenAPI Generator.

See the Environments page for details on the actual location of the different API specifications.

How to use OpenAPI Generator

Note

You will need to have Java installed to be able to use the OpenAPI Generator tool.

The simplest method for getting started is to download the JAR file for the OpenAPI Generator.
This allows you to run it yourself from your command line (CMD, PowerShell, Bash etc).

Example (for Java):

java -jar openapi-generator-cli/target/openapi-generator-cli.jar generate \
     -i https://api.purefarming.com/data/spec/streaming/oas3.json \
     -g java \
     -t modules/openapi-generator/src/main/resources/Java \
     --additional-properties artifactId=petstore-okhttp-gson,hideGenerationTimestamp:true \
     -o examples/client/pfStreamingApi/java/okhttp-gson

The above example shows that actually generating a client library is relatively straightforward using the tool. It provides options for most languages and tooling.

We recommend that the generation of the client library becomes part of either your build or pre-build process to ensure that your code is using the latest version of the API.

We also recommend that all client libraries be generated from the production versions of the OpenAPI specifications, as this will reduce the likelihood of breaking changes between environments.

The benefit of generating client libraries is that it reduces the amount of code you have to write and maintain, as the generator will produce all the API calls, models and other code you need. This includes the entirety of the Pure Farming Schema (as found here) which significantly reduces the work required to interact with the objects returned from the API.

Examples

java -jar ./openapi-generator-cli.jar generate \
      -i https://api.purefarming.com/data/spec/data/oas3.json \
      -g csharp-netcore \
      -o ./output/dotnet \
     --skip-validate-spec \
     --additional-properties netCoreProjectFile=true,packageName=PureFarming.Output.Data.Api;

java -jar openapi-generator-cli/target/openapi-generator-cli.jar generate \
     -i https://api.purefarming.com/data/spec/data/oas3.json \
     -g java \
     -t modules/openapi-generator/src/main/resources/Java \
     --additional-properties artifactId=purefarming-dataapi,hideGenerationTimestamp:true \
     -o ./output/java

java -jar openapi-generator-cli/target/openapi-generator-cli.jar generate \
     -i https://api.purefarming.com/data/spec/data/oas3.json \
     -g python \
     -t modules/openapi-generator/src/main/resources/Java \
     --additional-properties packageName=purefarming_data_api,hideGenerationTimestamp:true \
     -o ./output/python

Using the Streaming API

There are a couple of ways that you can use the Streaming API:

You can identify the resource types you are interested in, and only request those
You can programmatically iterate through the available resource types and request them

As described in the Streaming API Guide, you can programmatically request the data-sets that are currently provided.
This is done using the /data/streaming/datasets endpoint, which returns the set of currently known data-sets with their URLs to access them, e.g.:

[
    {
        "name": "holdings",
        "url": "https://api.purefarming.com/data/streaming/datasets/holdings",
        "changes": "https://api.purefarming.com/data/streaming/datasets/holdings/changes",
        "updates": "https://api.purefarming.com/data/streaming/datasets/holdings/updates",
        "containedTypes": [
          "holdingResource"
        ]
    },
    ...
]

Once you have the data-sets you are interested in, you simply call the changes endpoint for each data-set until you only receive two items (the "id" token and the "continuation" token).

The below diagram outlines the general process for fetching data from the Streaming API for a given dataset.
The steps are as follows:

Check if you already have a continuation token
If you do, pass it when you make the request to the changes endpoint
Fetch the data from the changes endpoint
Check the number of items returned, if there are more than two: a. Process the incoming data b. Get the continuation token for next use
If there are only two items in the response, save the continuation token for next use

%%{init: {'theme':'neutral'}}%%
flowchart LR
  s((Start))
  ct{Already\nhave Token?}
  f[/Fetch Data/]
  c{No. of Items\nReturned?}
  p[/Save Continuation\nToken/]
  pd[/Process Data in\nYour System/]
  e((End))
  s-->ct
  ct--->|Pass Token w/\nRequest|f
  ct-->|Just get Data|f
  f--->|Check count items|c
  f-->pd
  c-->|Greater than two\nitems Returned|f
  c-->|Only two items\nReturned|p
  p-->e

For more information about the Streaming API, see the API Reference and Guide.

Using the Data API

The Data API is a standard RESTful API which exposes the various resource types of data that Pure Farming can supply.

Generally speaking the Data API exposes data in four endpoints per resource type:

Resource	Description
`/data/livestock/animals`	Fetches all animals that you have access to
`/data/livestock/animals/{id}`	Fetches a single animal regardless of which Holding it is recorded against
`/data/holdings/{holdingId}/livestock/animals`	Fetches all animals you have access to on a given Holding
`/data/holdings/{holdingId}/livestock/animals/{id}`	Fetches a single animal on a given Holding

The above example is using the icarAnimalCoreResource resource type, however it holds true for other resources types as well.

For more information on the endpoints that the Data API exposes, see the API Reference listing for detailed info.
We recommend that you generate an API client in the language you are working in to make working with the API easier, as well as providing objects for the responses. See How to use OpenAPI Generator for more information. This is particularly useful for the Data API.

Using Webhooks

Webhooks may also be used if you require to be notified about changes in data as they happen.

For the payload of our webhooks, we make use of the existing cloud events standard to provide the events in a standardised format that you can consume. See cloudevents for more information.

For the specification see: JSON Event Format.

For more information on how they can be configured, please see the Webhooks page.

Table of Contents