The REST API is an HTTP web server commonly referred to as “The API”, “The REST API” or simply “The Server”. The REST API handles a number of responsibilities including:

  • Data storage, validation, and security: Prevents data loss between reflashes by storing it in a centralized database, allows users to edit information when the device is offline, validates data and controls access to data via authentication and authorization mechanisms.
  • Email delivery: Sends email notifications (such as password resets and critical errors) to end users. All other messaging is handled by the Message Broker, a distinctly decoupled sub-system of the Web API.
  • Image uploads and manipulation: Re-sizes and stores images captured by FarmBot’s internal camera.

Generally speaking, the REST API does not control FarmBot. Device control is handled by the Message Broker, CeleryScript and FarmBot JS.

API specifications
Web Framework Ruby on Rails
Authorization Mechanism JSON Web Tokens
Deployment Methodology 12 Factor
API Architectural Style REST
Database PostgreSQL
Test Framework RSpec
File Storage Mechanism Google Cloud Storage or filesystem (configurable)
Error Monitoring Rollbar (optional)
OS Ubuntu (not configurable)
Continuous Integration System Circle CI (optional)

Resources

Resources are JSON documents that can be downloaded from the server and used by devices, humans, and third-party tools to store FarmBot related information. Resources have names like “tool”, “plant”, “device” and “user”.

Every resource has a URL, and the HTTP verb used to access the URL will determine how the server handles the request:

HTTP verb Action
GET View resource(s).
PUT, PATCH Update or replace a resource.
POST Create a new resource.
DELETE Destroy a resource.

As an example, if we wished to change the name of our device to “Carrot Overlord”, we could perform an HTTP PUT to the URL https://my.farm.bot/api/device/325 with the following request body:

{
  "name": "Carrot Overlord"
}

Such a request would generate the following JSON HTTP response:

{
  "id": 325,
  "name": "Carrot Overlord",
  "timezone": "America/Curacao",
  "last_saw_api": null,
  "last_saw_mq": null,
  "tz_offset_hrs": -4,
  "fbos_version": null,
  "throttled_until": null,
  "throttled_at": null
}

Resource list

As of February 2020, the API manages the following resources:

Resource Description
alerts A single item in the message center. Only useful to site administrators.
corpus A glossary of all Celery Script node types in JSON format.
device Device account settings.
export_data A dump of all the resources listed above.
farm_events Executes a sequence or regimen based on time. Eg: “Execute this sequence every 6 hours”.
farmware_envs Key/value pairs used for persistent storage.
fbos_config Configuration for FarmBot OS.
firmware_config Configuration for the Arduino Firmware
folders Organization for sequences.
global_bulletins (advanced)An announcement intended for all users of a server
global_config Configuration for all users of a server.
images Meta data about photos taken by FarmBot.
logs Messages from a device.
peripherals Meta data about output hardware.
pin_bindings Bind an I/O pin to sequence execution.
plant_templates A single plant within a saved garden. Not a real plant.
points Represents a saved point on the garden bed. All point types are included in this resource: Plants, Weeds, Tool Slots, and Generic Points.
point_groups A collection of points based on a criteria or predefined set of points (eg: “All Weeds”, “My Basil Plants” etc..)
public_key (advanced) A public encryption key owned by the API server.
regimens Executes sequences based on an offset from the regimen start date.
releases FarmBot OS releases.
saved_gardens A pre arranged configuration of plants in a garden.
sensor_readings A single reading from a sensor, recorded to the API.
sensors Meta data about input hardware.
sequences Commands created in the sequence editor.
storage_auth (advanced) A policy object for Google Cloud Storage.
tokens An authorization / authentication secret shared between a user or device and the API.
tools An physical object that is mounted to the gantry or a tool slot (UTM).
users Device operator data such as registration email.
web_app_config User interface preferences.
webcam_feeds Meta data about an external webcam (stream URL)
wizard_step_results Setup wizard result data.

Pagination

Some endpoints will return so much data that it is desirable to break the results into smaller “pages” of a fixed length.

Some (but not all) API endpoints support pagination of GET requests. For example, if you wished to only download the third page of sensor_readings and you would like to set a page size of 10 items, you could perform the following request:

GET https://my.farm.bot/api/sensor_readings?page=3&per=10

In the example above, you may notice that the GET request contains a special query string for the page size (&per=10) and page number (?page=3).

The following resources support pagination: alerts, farm_events, farmware_envs, peripherals, pin_bindings, plant_templates, point_groups, regimens, saved_gardens, sensor_readings, sensors, tools, webcam_feeds.

You may request pagination for other resources by submitting an issue on Github.

Points endpoint

While the REST API is relatively uniform in how it handles resources, all plants, weeds, tool_slots, and generic points fall under the same /api/points endpoint. This endpoint also has some additional capabilities that the other endpoints do not.

Bulk deletion

Unlike the other API endpoints, the points endpoint supports bulk deletion. It is possible to delete many point resources in one request by separating many point IDs with a comma.

DELETE https://farm.bot/api/points/1,4,23

Filtering

When points are deleted, it is still possible to view them for 2 months after the time of deletion. This is useful for tools relating to weeding and historical records.

The /api/points/ endpoint supports a special ?filter= query parameter. There are three options for this parameter:

  • ?filter=all returns archived and active points.
  • ?filter=old only returns archived points.
  • ?filter=kept only returns active (not-archived) points. This is the default behavior for index (/api/points) endpoint.

Generating an API token

You must pass a token string into most HTTP requests under the Authorization request header. Here are some ways in which you can get a token. Also see our web app API examples.

curl -H "Content-Type: application/json" \
     -X POST \
     -d '{"user":{"email":"test123@test.com","password":"password123"}}' \
     https://my.farm.bot/api/tokens

// Since the API supports [CORS](http://enable-cors.org/), you can generate your
// token right in the browser. Here's an example:

$.ajax({
    url: "https://my.farm.bot/api/tokens",
    type: "POST",
    data: JSON.stringify({user: {email: 'admin@admin.com', password: 'password123'}}),
    contentType: "application/json",
    success: function (data) {
                 // You can now use your token:
                 var MY_SHINY_TOKEN = data.token.encoded;
             }
});

import requests
response = requests.request(
    method='POST',
    url='https://my.farm.bot/api/tokens',
    headers={'content-type': 'application/json'},
    json={'user': {'email': 'admin@admin.com', 'password': 'password123'}})
TOKEN = response.json()['token']['encoded']

And here’s what the response will look like:

{
    "token": {
        "unencoded": {
            ...
            "iat": 1459109728,
            // USE THIS AS YOUR USERNAME WHEN LOGGING INTO THE MESSAGE BROKER:
            "bot": "device_456",
            "jti": "922a5a0d-0b3a-4767-9318-1e41ae600352",
            "exp": 1459455328
        },
        "encoded":
        // THE IMPORTANT PART IS HERE (shortened for clarity):
         "eyJ0eXAiOiJ...Ry7CiA"
    }
}

The response is provided as JSON for human readability. For your Authorization header, you will only be using data.token.encoded. In this example, it’s the string starting with eyJ0eXAiOiJ...

Security

The API uses JSON Web Tokens for authentication and authorization (see “Frequently Asked Questions” section for token generation instructions). Additionally, it uses Content Security Policies to prevent unauthorized access by malicious software on client machines.