API/Version 1

Draft status
We are currently designing version 1 of the Growstuff API. There is nothing for you to use, yet. See Version 0 documentation for something you can use right now.

Requirements
We are gathering requirements for the 1.x API via the api-discuss mailing list. Please subscribe to that list if you would like to take part in these discussions.

The following is a summary of what we want. If you'd like to be able to edit this page directly, request a wiki account. (It should be approved within a day. Sorry, we can't have open editing due to spam.)

api.growstuff.org
The API should be served off of, to keep it separate from the main site, and so that (as and when necessary) we can do rate-limiting or other traffic management independently of.

See: http://collectiveidea.com/blog/archives/2013/06/13/building-awesome-rails-apis-part-1/

Versioning
The major versions of the API (v1, v2, etc) should be kept separate in the codebase, as per the example given in http://collectiveidea.com/blog/archives/2013/06/13/building-awesome-rails-apis-part-1/

Include licensing info
We should make sure that our open data license info is really clearly visible in the JSON responses we give to our API. Something like:

license: { name: "Creative Commons Attribution ShareAlike 3.0 Unported", short_name: "CC-BY-SA", url: "http://creativecommons.org/licenses/by-sa/3.0/", credit: "Growstuff", link: "http://growstuff.org/", easy_link: "&lt;a href="http://creativecommons.org/licenses/by-sa/3.0/">CC-BY-SA&lt;/a> &lt;a href="http://growstuff.org/">Growstuff&lt;/a>" }

The easy link, in particular, should include whatever snippet of HTML we'd ideally like them to include when they credit us for the data they get via our API.

Similar information should be made available for photos etc, so that the correct person can easily be attributed.

Include useful data related to an object in response
When you request an object like eg. a crop, the response should include data such as plantings, seeds, locations, etc related to that crop, even if (in Rails) they are other objects.

As a simple example, a request for a single post should include all that post's comments in the response.

Mailing list thread: http://lists.growstuff.org/pipermail/api-discuss/2013-August/000004.html