API Overview
AgriWebb provides customers with access to their data through an API. This allows customers to extract data for use in custom reporting systems as well as a way to push IoT data into the platform.
Visit this site for our offical documentation
The API is based on GraphQL, which is an alternative to RESTful APIs. There are a lot of benefits to using GraphQL, but the primary ones are:
Flexibility in accessing data. Rather than developing an API end-point for each type of object that is retrieved, a GraphQL API offers a single end-point with the ability to specify the objects that are being retrieved.
Control over the retrieved data. Each API call must explicitly define the data that will be returned for each request. While the API requests are larger, users can define the exact fields returned, reducing the overall payload response size.
Accessing the API
The AgriWebb API can be accessed here:
You can explore the API by connecting to the URL above in a web browser. This is called the API Playground. The list of types that can be accessed through the API and their schema is documented in the API Playground.
You can construct queries against the API in the Playground. The Playground offers code completion and includes the API documentation as well as the API Schema for generating client libraries using other GraphQL tools.
In order to execute a query, you will need an API key. API keys are currently obtained directly from the AgriWebb Development Team and feature fine-grained access control.
You can specify the API key to use in the Playground with the following string in the HTTP Headers section:
{
"x-api-key": "YOUR_API_KEY"
}
Examples
Retrieving data
Retrieve the name and ID for all farms this key has access to.
{
farms {
id
name
}
}
Retrieve information about all map features on farms this key has access to.
{
mapFeatures {
id
name
type
farmId
}
}
Retrieve water tanks on a specific farm.
{
waterTanks: mapFeatures(
filter: {
type: { _eq: WATER_TANK }
farmId: { _eq: "YOUR_FARM_ID" }
}
) {
id
name
alert {
critical
warning
}
capacity {
mode
value
unit
}
}
}
Retrieve animals on a given farm.
{
animals(farmId: "YOUR_FARM_ID") {
animalId
identity {
vid
}
characteristics {
sex
birthYear
}
state {
weights {
liveWeight {
value
unit
}
}
}
}
}
Retrieve animals on a given farm with paging. Limit is the number of results to return in the request, skip is the number of items to skip before returning the result. Note that skip is the number of items, not the number of pages.
{
animals(farmId: "YOUR_FARM_ID", limit: 50, skip: 100) {
animalId
}
}
Retrieve weight records for animals on the specified farm.
{
animals (farmId: "YOUR_FARM_ID") {
animalId
identity {
vid
eid
}
records (filter: {recordType: {_eq: weigh}}) {
recordType
recordId
observationDate
... on WeighRecord {
weight {
value
unit
}
}
}
}
}
Retrieve animals above a specific weight on a given farm.
{
animals (
farmId: "YOUR_FARM_ID"
filter: {
state:{
weights:{
liveWeight:{
unit:kg, value:{_gt:200}}
}
}
}
) {
animalId
identity {
vid
}
characteristics {
sex
birthYear
}
state {
weights {
liveWeight {
value
unit
}
}
}
}
}
Posting data
Add a reading to a rain gauge and retrieve the corresponding time and mode for the saved reading.
Sensor ID is currently the same as the map feature’s ID. This will change when AgriWebb supports multiple sensors on a single map feature, such as a weather station or water tank instrumented with a depth gauge for capacity readings and a rainfall gauge.
mutation {
addRainfalls(input:{
unit:mm
value:10
farmId: "YOUR_FARM_ID"
sensorId:"YOUR_SENSOR_ID"
time:1575949204002
mode:cumulative
}) {
rainfalls {
time
mode
}
}
}