Notas sobre diseño de APIs

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",
  }
}

Leave a Reply

Your email address will not be published.

Time limit is exhausted. Please reload CAPTCHA.

This site uses Akismet to reduce spam. Learn how your comment data is processed.