JSON Data API cleanup for consistency

[ErisDS]

The API needs:

• a clear naming convention for functions
• some thought about the names of non BREAD functions
• a clear naming convention for options / arguments
• some thought about what options / arguments are available to each function
• clear convention for return values
• consistent behaviour for error and warning handling

Once this work is complete, we should rename the API routes from v0.1 to v1.0

---

Update by @ErisDS 10-04-14:

As a result of the discussion which occurred in #2362, we now have a clear plan of what we want to do with our API in order to make it clear, consistent and easy to make decisions about how things should work.

We want to move our API towards supporting JSON-API, but with one major difference - all included objects should get included inline, rather than using linked objects. Linked object support will be added in the future via some sort of switch.

The move towards the JSON API response format includes a number of distinct changes:

• The response is an object with a number of keys, one of those keys should be the pluralised name of the primary document type which is being returned. In terms of Ghost, this means posts, tags, users, settings etc.
• The response object can also contain a meta key, this will be used to return pagination data
• The key for the primary document type always contains an array, even when only one object is returned. Therefore the response for a single post would look like: { posts: [{ id: 1, uuid: ... } ] }
• Related objects should default to using their relation name as the key. Therefore in the post response, there should be an author key, not an author_id key.
• Related objects should only be exanded into full objects when explicitly declared with include.
• The headers on the response should include a content-type header of 'application/vnd.api+json', 'application/json'.
• The response to a create request should include a location header like Location: http://myblog.com/ghost/api/posts/12`
• The keys for pagination data should be moved into a top-level meta object
• We should add support for PATCH requests (long term)
• We should add support for the sort query param (long term)

There are quite a few changes, some of them bigger and harder than others, the following is a list of issues which should get us from where we are to where we want to be.

• Move to primary document format: Posts Post API: move to primary document format #2580, Tags~~ Tag API: move to primary document format #2605~~, Users User API: move to primary document format #2593, Settings Settings API: move to primary document format #2606, DB DB API: request / response format #2647?, Mail Mail API: Move to primary doc format + status messages #2650?,
• Notifications API: Proper endpoints for persistent notifications Notifications API: Proper endpoints for persistent notifications #2637
• Tag API: parent relation Tag API: parent relation #2607
• Post API: author relation Post API: author relation #2608
• Post API: pagination -> meta Post API: pagination -> meta #2604
• Post API: Explicit includes Post API: Explicit includes #2609
• Non-REST function / route names Non-REST function / route names #2601
• Options vs Args [Discussion] Options vs Args for API methods #2610
• Internal cleanup / consistency
• Provide proper status codes for API operations Provide proper status codes for API operations #2187
• Error messages Error message responses #2643, Add distinct error classes #2690
• Complete documentation JSON Data API Docs #2125