Quiero recomendaros que veáis el vídeo de YouTube llamado RESTful API design de Brian Mulloy. En este artículo hago un pequeño resumen de las ideas más importantes del vídeo, por supuesto desde mi punto de vista:
-
Usa sustantivos plurales concretos cuando estés definiendo recursos.
-
La URL del recurso tiene que estar centrada en el acceso a la colección de elementos y al elemento concreto. Ejemplo:
-
/clients - obtener todos los clientes
-
/clients/23 - obtener el cliente con ID 23
-
Mapear los métodos HTTP a los elementos de mantenimiento (CRUD):
-
POST - CREATE
-
GET - READ
-
PUT - UPDATE
-
DELETE - DELETE
-
Workaround, si tu cliente REST no soporta los métodos HTTP, usar un parámetro llamado 'method' podría ser una buena idea. Por ejemplo, cuando tengas que usar un método HTTP PUT se podría cambiar por el método HTTP GET y el parámetro 'method=put' en la URL.
-
Aparta la complejidad detrás de la '?'. Usa parámetros en la URL para filtrar o poner alguna información opcional en tu petición.
-
Cómo gestionar los errores:
-
Usa los códigos de respuesta HTTP para referir los códigos de error. Puedes encontrar una lista de códigos de respuesta HTTP en Wikipedia.
JSON response example can be like this:<br><pre>{ 'message':'problem description', 'more_info':'http://api.domain.tld/errors/12345' }</pre><br>
Workaround, si el cliente REST no sabe cómo capturar los códigos de error HTTP y lanzar un error perdiendo el control del cliente, puedes usar el código de respuesta HTTP 200 y poner el campo 'response_code' en el objeto de respuesta JSON. Es una buena idea usar esta funcionalidad como opcional a través del parámetro de URL 'supress_response_code=true'.
Versionar la API. Usa una letra 'v' literal seguida de un número entero antes de la referencia al recurso en la URL. Podría ser la solución más simple y potente en este caso. Ejemplo: /v1/clients/
La selección de qué información se devolverá en la respuesta se puede definir en los parámetros de la URL, como en este ejemplo: /clients/23?fields=name,address,city
Paginación de la respuesta. Usa los parámetros 'limit' y 'offset', mantente simple. Ejemplo: ?limit=10&offset=0
Formato de la respuesta, en este caso no estoy del todo de acuerdo con Brian. Prefiero usar la cabecera HTTP 'Accept' que su propuesta. De todos modos ambas ideas son:
-
Usar la cabecera HTTP 'Accept' con la petición de formato adecuado en la respuesta, por ejemplo, 'Accept: application/json' cuando quieres una respuesta JSON.
-
o, usar la extensión '.json' en la URL de la petición para obtener la respuesta en formato JSON.
-
Usa el formato Javascript para la información de fecha y hora, cuando estés formateando objetos JSON.
A veces las APIs necesitan compartir acciones. Entonces no podemos definir una acción con un sustantivo, en este caso usa un verbo. Es común necesitar acciones como: convert, translate, calculate, etc.
Buscar, hay dos casos:
-
Buscar dentro de un recurso, en este caso usa parámetros para aplicar filtros.
-
Buscar a través de múltiples recursos, aquí es útil crear el recurso 'search'.
-
Contar elementos dentro de un recurso, simplemente añade '/count' después del recurso. Ejemplo: /clients/count
-
En la medida de lo posible usa una única URL base para todos los recursos de la API, algo así como: 'http://api.domain.tld'.
-
Autenticación, simplemente usa OAuth 2.0
Para mantener tu API KISS normalmente es una buena idea desarrollar SDK en varios lenguajes, donde puedes poner más funcionalidades de alto nivel que en la API.
Dentro de una aplicación cada recurso tiene su propia API pero no es una buena idea publicarla al mundo, quizá usar una API virtual en una capa por encima es más seguro y potente.