-
Notifications
You must be signed in to change notification settings - Fork 210
API Version 0
As of mid-2013, this version of the API is live and available on the Growstuff website (http://growstuff.org/). However, it should be considered of "alpha" quality. While giving access to most of the important data in our system, it is subject to change and intended more as a demonstration of what data we have available, than something you'd want to build a stable production service on. See Version 1 documentation for a new, improved API we're working on ca. 2014.
Broadly speaking, you can get a JSON representation of any class of things in Growstuff, or any individual thing, by sticking .json 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 .json 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 render :json 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.
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.
| what? | List (HTML, human-readable) | List (JSON) | Single item (JSON) |
|---|---|---|---|
| Crops | /crops | /crops.json | /crops/ID.json |
| Gardens | /gardens | /gardens.json | /gardens/ID.json |
| Plantings | /plantings | /plantings.json | /plantings/ID.json |
| Seeds | /seeds | /seeds.json | /seeds/ID.json |
| Posts | /posts | /posts.json | /posts/ID.json |
| Comments | /comments | /comments.json | /comments/ID.json |
| Photos | /photos | /photos.json | /photos/ID.json |
| Places | /places | /places.json (mappable items) | /places/ANYWHERE.json (mappable items near the specified place) |
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.)
| What? | HTML | JSON |
|---|---|---|
| Gardens | /gardens/owner/ID | /gardens/owner/ID.json |
| Plantings | /plantings/owner/ID | /plantings/owner/ID.json |
| Seeds | /seeds/owner/ID | /seeds/owner/ID.json |
| Posts | /posts/author/ID | /posts/author/ID.json |
NOTE: posts uses "author" rather than "owner".
For datasets which are paginated (as the Crops page is) you can add ?page=N (where N is an integer) to get subsequent pages. There is no facility, at present, for finding the total number of items or pages.
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.