V3 API SPEC PROPOSAL
====================
We want to standardize public API responses so that consumers have a reasonable idea of what to expect back. This will also allow us to write global reusable components that handle errors, unwrap data, and create pagination. Http Methods
-----------GET
: Retrieving resources and lists of resources
POST
: Creating resources
PUT
: Updating resources
DELETE
: Deleting resources
Http Response Codes
------------------Because HTTP codes and actual API states don't map 1:1 using more granular codes doesn’t make sense. We should only return one of the following...
200 - OK
400 - User Error
500 - StudyMode Error
More fine-grained error codes should be sent back the error key.
{
error: { code:4012 message: ‘you really messed up’
}
}
Response Object
--------------Api will only return JSON data.
An API Response should always return a data object with the following keys. data : Contains an object or list of objects with the requested data. meta : Contains keys for pagination. error : Contains error information codes and descriptions
{
'data': { ... } or [ ... ],
'meta': { ... },
'error': { ... } or null
}
Pagination
---------Located in the meta key. The following keys will allow a full pagination component to be built. limit: count: page: last:
Maximum number of records to return per request (default 100?)
Total number of records available
What subset of records to return (index starts at 1)
The last available page available to current resource
Request Params
-------------limit:
Maximum number of records to return per request (default 100?) page: What subset of records to return (index starts at 1) fields: A list of fields to include in the response; all other fields will be filtered out. Nested fields can be denoted by a colon,
