Web API

The Web API is a collection of methods that allow your integration to interact with a user's farm. You can use this API to both read and write data whenever you need to.

Communicating with the API

All of the methods in the Web API are requested using either GET or POST to a URL of the form:

https://api.fieldmargin.com/METHOD

Request and response bodies will always be JSON unless otherwise specified. When you send JSON to the API you should provide the appropriate content type header:

Content-Type: application/json

All methods return a simple HTTP status code that describe the outcome of the request, as follows:

Status	Description
200	Request was successful and a response has been provided
400	The request was invalid and couldn't be fulfilled. This likely represents an error with how the integration is using the API.
500	An internal error occurred unexpectedly. This represents an error by fieldmargin and we endeavour to avoid these.

Authentication

Requests to the Web API must be authenticated using an access token generated in the authorization flow. This token should be included as header to the request, as follows:

Authorization: Bearer <ACCESS_TOKEN>

The access token will provide you with a set of permissions, that determine which methods you are allowed to access.

Errors

Example error

{
    "error": "invalid_token",
    "message": "No access token provided"
}

When a request to the Web API results in an error, we will provide details in the response body:

Field	Description
error	A short string to describe the type of error
message	Optional human readable description to help you diagnose the issue

We recommend that you depend on the error field for your error handling, the HTTP status is only provided as a hint and messages may change frequently. Common error codes you may experience are:

Code	Description
invalid_token	An access token was not provided, was not recognized, or access to a farm has been revoked.
missing_scope	The access token is valid but does not have permission to access the requested resource.
no_such_method	The requested URL does not exist.
bad_request	The request parameters or request body failed validation.
not_found	The entity that was requested doesn't exist.

Additionally, each method in the API may define its own error cases.

Backwards Compatibility

We aim to maintain full backwards compatibility when making changes to the API, so that any requests you make now will work for the foreseeable future.

We will however be constantly updating the API with new methods and new functionality. We may also add new fields to request and response bodies; your systems should ignore any fields that they do not understand.