-
Notifications
You must be signed in to change notification settings - Fork 210
API Version 1
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.
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 api.growstuff.org, 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 www.growstuff.org. 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/
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: "<a href="http://creativecommons.org/licenses/by-sa/3.0/">CC-BY-SA</a> <a href="http://growstuff.org/">Growstuff</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.
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
These are some useful links/reading for people working on creating this API:
- Building awesome Rails APIs
- If you're using to_json you're doing it wrong
- Building a platform API on Rails
- RABL (Ruby API Builder Language)