Después de releer el libro de Phil Sturgeon Build APIs you won’t hate dejo aquí estas notas a tener en cuenta para el diseño de APIs:
- No usar un número autoincremental como identificador de los recursos, es mejor utilizar un identificador alfanumérico.
- Nombres de los recursos en plural (places, users, etc.)
- Los nombres de los recursos no deben ser verbos sino sustantivos. Por ejemplo, en vez de /users/5/send-message es mejor /users/5/messages
- Para generar documentación: Api Blueprint
- Principales códigos de respuesta:
- 200 – Generic everything is OK
- 201 – Created something OK
- 202- Accepted but is being processed async (like video encodings)
- 204 – The server has successfully fulfilled the request and that there is no additional content to send in the response payload body
- 400 – Bad Request (should really be for invalid syntax but some folks use it for validation)
- 401 – Unauthorized (no current user and there should be)
- 403 – The current user is forbidden from accessing this data
- 404 – That URL is not a valid route, or the item resource does not exist
- 410 – Data has been deleted, deactivated, suspended, etc
- 405 – Method Not Allowed (your framework will probably do this for you)
- 500 – Something unexpected happened and it is the APIs fault
- 503 – API is not here right now, please try again later
- Ejemplo de paginado:
{
"data": […],
"pagination" :
{
"total": 1000,
"count": 12,
"per_page": 12,
"current_page": 1,
"total_pages": 84,
"next_url": "/places?page=2&number=12",
}
}