StatusCodes

Structure

Over all structure is a valid json dictionary which contains the http status code, related message, and a link back to the documentation for more info.

REQUEST
{
        'code': <STATUS_CODE>,
        'message': <MESSAGE>,
        'more_info': <URL>
}

Formal BNF Notation:

REQUEST     ::= <GET|PUT|DELETE|POST|OPTIONS>
STATUS_CODE ::= DIGIT ["." DIGIT]
MESSAGE     ::= (LOALPHA | "-")+
URL         ::= valid URL string following the RFC 1738

Codes

HTTP Verb	CRUD	Collection (e.g. /assets)	Object (e.g. /assets/{id})
POST	Create	201 (Created)	'Location' header with link to /assets/{id} containing new ID.
GET	Read	200 (Success), list of assets. Use pagination, sorting and filtering to navigate big lists.	200 (Success), single customer. 404 (Not Found), if ID not found or invalid.
PUT	Update	404 (Not Found), unless you want to update/replace every resource in the entire collection.	200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid.
DELETE	Delete	404 (Not Found), unless you want to delete the whole collection—not often desirable.	200 (OK). 404 (Not Found), if ID not found or invalid.
OPTION	N/A	200 (success) returns a message body and an ALLOW header, that state all the methods the current resource is capable of handling. If resources require authentication, it is possible that OPTIONS returns more methods once you added authentication headers to the request

Self documented API

a request like OPTIONS /assets/:id/issue should respond with a body like...

{ "POST": { "description": "Create an issue", "parameters": { "title": { "type": "string" "description": "Issue title.", "required": true }, "body": { "type": "string", "description": "Issue body.", }, "assignee": { "type": "string", "description" "Login for the user that this issue should be assigned to." }, "milestone": { "type": "number", "description": "Milestone to associate this issue with." }, "labels": { "type": "array/string" "description": "Labels to associate with this issue." } }, "example": { "title": "Found a human", "body": "I'm having a problem with this.", "assignee": "cacodaemon", "milestone": 1, "tags": [ "redfish", "bluefish" ] } } }