API v2 design

[c8y3]

I am starting this discussion about the REST API v2 design.

Here are some rules the new REST API should adhere to :

• use verbs POST to create, GET to read, PUT to update and DELETE to remove
• resources which return collections should end with an 's'
• resources which return collections should be paginated
• resources which return collections should include fields total, data, last_page, current_page and next_page
• in case of success, GET and PUT endpoints should return code 200 and return the object
• in case of success, POST endpoints should return code 201 and the newly created object
• in case of success, DELETE endpoints should return code 204 and an empty body
• in case an object is not found, GET endpoints should return code 404
• in case of some other error, endpoints should return 400 and an object which contains at least a field message with the error message
• enpoints' urls should not contain verbs
• identifiers (in query parameters, body and results) should have type integer
• given an url /api/v2/resources, the object returned with POST, should have the same type as the objects returned in GET /api/v2/resources and the object returned in PUT/GET /api/v2/resources/{identifier}