Agworld User API Documentation

Introduction

The Agworld API is an implementation of the JSON API specification. It is currently Read-Only.

Example Reference Client Implementation

Here is a link to an example reference client implementation written in Ruby: https://github.com/agworld/agworld_api_client

URL

In the examples below, please substitute <url> with the appropriate url for the instance that you are connecting with. A non-exhaustive list of Agworld instances is listed below:

• Australia - https://my.agworld.com.au
• The United States - https://us.agworld.co
• New Zealand - https://nz.agworld.co

Content-Type

Clients must include the following headers with each request:

Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

The API will include the following headers with each response:

Content-Type: application/vnd.api+json

Authentication

Authentication is token based. If you wish to request additional Agworld API Access please contact Agworld support: https://help.agworld.com/en/articles/2497766-how-to-contact-agworld-customer-success

The token must be supplied along with each request in one of two ways:

1. As a request parameter e.g.

    curl <url>/user_api/v1/fields?api_token=token \
    -H 'Content-Type: application/vnd.api+json' \
    -H 'Accept: application/vnd.api+json'
   

2. As a header parameter e.g.

    curl <url>/user_api/v1/fields \
    -H 'Content-Type: application/vnd.api+json' \
    -H 'Accept: application/vnd.api+json' \
    -H 'Api-Token: token'
   

Features

The following JSON API functionality is implemented for each resource’s endpoints (index and show). Please check the JSON API specification for more detail on each of these options.

Note The URL’s passed to curl below are not URL-encoded. This makes reading them easier but it means that they will need to be properly encoded before using them yourself. For example [ and ] become %5B and %5D respectively.

• filter (index only)

  Allows the filtering of the records returned in the response by the specified attribute. The list of filterable attributes is defined for each resource in its specific section.

    curl <url>/user_api/v1/farms?filter[name]=Home \
    -H 'Content-Type: application/vnd.api+json' \
    -H 'Accept: application/vnd.api+json' \
    -H 'Api-Token: token'
  

• sorting (index only)

  Allows the sorting of the records in the response by the specified attribute. The list of sortable attributes is defined for each resource in its specific section.

    curl <url>/user_api/v1/farms?sort=name \
    -H 'Content-Type: application/vnd.api+json' \
    -H 'Accept: application/vnd.api+json' \
    -H 'Api-Token: token'
  

• pagination (index only)

  The Agworld API uses pagination for each index endpoint with a default page size of 10 and a maximum of 100. To fetch a specific page, a client should provide a page[number] parameter. It is also possible to optionally override the size of the page returned by providing a page[size] parameter.

    curl '<url>/user_api/v1/farms?page[number]=2&page[size]=5' \
    -H 'Content-Type: application/vnd.api+json' \
    -H 'Accept: application/vnd.api+json' \
    -H 'Api-Token: token'
  

• include

  For efficiency, it is possible to side-load related records in the same request. The list of includable records is defined for each resource in its specific section.

    curl <url>/user_api/v1/farms?include=company \
    -H 'Content-Type: application/vnd.api+json' \
    -H 'Accept: application/vnd.api+json' \
    -H 'Api-Token: token'
  

• fields

  For efficiency, it is possible to only return a subset of the fields available on a resource. The list of visible attributes is defined for each resource in its specific section.

    curl '<url>/user_api/v1/farms?fields[farms]=name' \
    -H 'Content-Type: application/vnd.api+json' \
    -H 'Accept: application/vnd.api+json' \
    -H 'Api-Token: token'
  

Webhooks

You can subscribe to HTTP Webhooks for Create, Update and Delete for each of the sources above. After adding a Webhook any records that you have access to read will trigger these events and a POST request will be made against the webhook URL with the record’s payload in the same JSON API format that the rest of the API uses.

The payload also contains a ‘meta’ attribute called ‘event’ which will be one of “Create”, “Update”, “Delete” and signifies the event that took place.

Object lifecycle and Webhook event ‘bundling’

In order to better represent user behaviour and to prevent redundant events we have 2 mechanisms that limit Webhook events from firing.

1. Initial creation window. There is a 4 second window immediately after an object is created where any updates are counted as part of the original creation. This means that if a user (or automated process) creates and immediately updates an object there will only be one Webhook invocation for the create event but it will include any changes from the update. A Webhook invocation for an update event will not happen in this case.

2. Subsequent updates window. Update Webhooks will fire a minimum of 1 minute apart. Any edits within a minute will extend this window and be ‘batched’ into one update event. This extending can indefinitely delay the update until ongoing updates stop happening within the 1 minute window.