RFC: API spec

[ryanolee]

This issue aims to outline the core entity CRUD pattern we can follow to get data from the API. Based on https://docs.google.com/document/d/1TU8z8vWfXIUVTVR_5cQaHcC0pmyWzLddRz8r3vOYVIg/edit Responses

To get a list of entities

Request

GET /entity

Response 200 on success and 500 on error

Pagination

GET /entity?offset=0&limit=50

Response 200 on success. 401 on no auth 404 on out of bounds error. 400 on bad values for offset or limits 500 on unrelated errors

To get a single entity

GET /entity/{id}

Responses: 200 on success 401 on no auth 404 on entity not found 403 on entity not belonging to user 500 on unrelated error

To create a single entity

POST /entity
Body: {...payload}

Responses: 201 on success 401 on no auth 500 on unrelated error

To update a single entity

PUT /entity/{id}
Body: {...payload}

Responses: 204 on success 401 on no auth 404 on entity not found 403 on entity not belonging to user 500 on unrelated error

To delete a single entity

DELETE /entity/{id}

204 on success 401 on no auth 404 on entity not found 403 on entity not belonging to user 500 on unrelated error

Error and content bodies can be be implemented as things move forewords with the backend and the error handling can be updated on the frontend to reflect the new format. Prefixes to the API and entity names can change but all API entities should follow this general format unless for special endpoints where we might need to fetch more data based on filter criterion. The implementation for such cases can be delt with at a later date

[tsukimi2]

@ryanolee I think I have enough time to take up this issue. ^_^