The OpenFarm API (ALPHA VERSION)

Overview

OpenFarm provides members with a publicly accessible, RESTful, JSON API. This API is still in an alpha state. The API can and will change abruptly and without notice.

To use the API, send HTTP requests to the same server/port on which your OpenFarm website is found. If you are running the server on your own machine, this will probably be http://127.0.0.1:3000/. The Advanced REST Client is a useful Chrome extension with which you can manipulate the parameters of REST requests and see how they operate.

The OpenFarm REST API is a little quirky in that it sometimes passes parameters to its GET requests rather than representing the parameters in the resource name itself. So for instance, in order to search for a crop, rather than requesting a resource with a request like GET /api/crops/query/foo you would issue a request like GET /api/crops?query="foo".

Cross Origin Resource Sharing (CORS)

The OpenFarm API supports CORS. This means that browsers can contact the OpenFarm API directly without the need of a trusted proxy / intermediary on the backend.

Token Authentication

To use some features of the API you must be authenticated. Currently, the API authenticates members via token authentication. Tokens auto expire 30 days after their creation date, at which point a member must re-authenticate with the server. Here are some examples of token interactions:

To use those parts of the API that require authentication, create a token and then add it to your HTTP REST request by adding a request header with the following format: Authorization: Token token=YOUR_TOKEN_HERE.

Example:

Authorization: Token [email protected]:123xycsefsdfsdfsdffs

You can use the same token for all subsequent requests until the time when the token expires or you deliberately revoke the token with a DELETE request.

How Do I Upload Images and Files to the API?

File Uploads (The Easy Way)

Host the image somewhere else (Your own server, Imgur, Photobucket, Flickr, whatever…)
Post the fully-formed image URL to the API as an attribute (e.g. if you are making a guide set {"featured_image":"http://lolcats.com/icanhaz.png"} within the appropriate field. Here is an example from the API docs.
A background worker will download the supplied URL and copy it to our file hosting server via a delayed job.

File Uploads (The Less-Easy Way)

Make an authenticated HTTP GET request to /api/aws. The response contains the following fields:

A security signature (“signature” field)
A security policy (“policy” field)
An AWS public access key (“key” field)

Do an HTTP POST request with the following fields:

success_action_status set to 201. If you do not set this, AWS will not give you an XML response, which you need to know the fully-formed URL of your temp file.
key set to temp/SOME_UNIQUE_IDENTIFIER.jpg. This is the filename of your tempfile. Client-side members are only allowed to put files into the temp/ folder.
acl key set to public-read.
Content-Type usually set to something like image/jpeg depending on the file variety
AWSAccessKeyId set to the key given in step 1.
policy set using the policy key in step 1.
signature set using security signature from step 1.
file set to the binary image you are uploading.