API/Version 0

This is the documentation for "version 0" of the Growstuff API.

Status
As of mid-2013, this version of the API is live and available on the Growstuff website (http://growstuff.org/).

However, it is extremely sketchy, extremely subject to change, and should be considered of "alpha" quality. It is intended more as a demonstration of what might be possible, than something you'd want to build a production service on.

See Version 1 documentation for a new, improved API we're working on ca. late 2013.

Really basic overview
Broadly speaking, you can get a JSON representation of any class of things in Growstuff, or any individual thing, by sticking  on the end of its human-readable URL. For instance, http://growstuff.org/crops gives you a webpage full of crops, while http://growstuff.org/crops.json gives you a JSON representation of the same crops.

To fetch the details of a single object, again just stick  on the URL. For instance, http://growstuff.org/crops/tomato.json gives you data about tomatoes. Note that "tomato" can be replaced by any numeric ID or URL slug, eg. "1.json" for the crop with numeric ID 1, or "butternut-squash.json" for data on the butternut squash crop. This applies equally to any/all objects -- crops, plantings, posts, etc.

REST API
Most classes of object in the Growstuff database provide an API endpoint. It emits the stock-standard JSON provided by Rails's  and has not been improved in any particular way.

You can, in theory, use this API to perform any action you can perform using the website, including creating/updating/deleting records. However, you'll need to figure out authentication for yourself, and it might be hairy. We don't particularly recommend it, and aren't going to document its use. This facility may also be removed at any time.

In short, the only recommended use of this "version 0" API is to "GET" lists of objects or individual objects.

What's available
Here's a list of most of the things we keep in our database, and how you can access JSON representations of them via our API.

Wherever this table says "ID" you can replace it with either a numeric ID, or the slug for an object, eg. "skud-backyard" for a garden or "popcorn" for a crop.

List by owner
For the following types of objects, you can get a list by owner/author, i.e. the member who created the thing. Replace "ID" with the numeric ID or the slug for the member in question. (The slug is, generally speaking, the login name all in lower case.)

NOTE that posts uses "author" rather than "owner".

Pagination
For datasets which are paginated (as the Crops page is) you can add  (where N is an integer) to get subsequent pages. There is no facility, at present, for finding the total number of items or pages.

Known limitations
The biggest problem with this API is that there is no way to traverse a one-to-many relationship starting with the 'one'. That is, if you have a crop, there's no way to find the plantings for that crop. (The other way around is possible, but takes two queries -- one for the planting and another for the crop -- to get all the details you might want.)

There is no way to search on any field or parameter, except the "by owner" endpoints mentioned above.

Pagination is a bit half-assed, in that there is no indication of which page you're looking at, or how many pages there are in total, in the JSON data.

The JSON API for certain objects (eg. members) has been removed for privacy reasons. It would be nice to be able to get information about members, though, in a non-privacy-invading way.