API V2 Design Guidelines

In an attempt to be consistent across API calls, I want to lay out some guidelines for api/2 calls so that we can do our best to stick to them as we continue to design and implement everything. Obviously, each call can take on a number of different formats each of which have pros and cons, so I am hoping that these guidelines will help us choose the most sensible and consistent ones.

THIS IS A WORKING DRAFT! Please comment...

• for POST and PATCH calls, the object being created should be at the root of the url i.e. POST api/2/sessions and any further parameters should be added as POST params.

• any ids included in urls should refer to the item immediately preceding them in the url itself

• GET api/2/project/2 returns data about project with id=2

• Generally speaking, a call that changes or creates an object should represent the entire new object in its response. This will allow for a easy verification of application state for the API consuming client.

• all calls should have example calls and example responses showing all possible params (optional and otherwise) to make it easier for those adopting the protocol. Ultimately I would like to see the common flow/changes/documentation wiki pages all merged into one that is a one-stop-shop. The "changes" section can be ultimately deleted or made less obvious but it seems it would be helpful to have everything in one place. (JZ)