Me llamó la atención el estándar RESTful hace poco cuando leí la presentación "RESTful API Design", por lo que investigué acerca de las mejores prácticas que quiero compartir...
1. Utilizar sustantivos, no verbos
Para una fácil comprensión utilizaré esta estructura para cada recurso:
| Resource | GET read | POST create | PUT update | DELETE |
| /cars | Returns a list of cars | Create a new ticket | Bulk update of cars | Delete all cars |
| /cars/711 | Returns a specific car | Method not allowed (405) | Updates a specific ticket | Deletes a specific ticket |
No usar verbos como:
/getAllCars
/createNewCar
/deleteAllRedCars
/createNewCar
/deleteAllRedCars
2. El método GET y los parámetros de consulta no deben alterar el estado
Usar los métodos PUT, POST y DELETE en lugar del método GET para alterar el estado.
No usar GET para cambios de estado:
GET /users/711?activate
GET /users/711/activate
GET /users/711?activate
GET /users/711/activate
3. Usar sustantivos en plural
No hacer un mix de estos. Sólo utilizar sustantivos en plural para todos los recursos.
/cars en vez de /car
/users en vez de /user
/products en vez de /product
/settings en vez de /setting
/users en vez de /user
/products en vez de /product
/settings en vez de /setting
4. Usar sub-recursos para las relaciones
Si un recurso está relacionado con otro, usar sub-recursos.
GET /cars/711/drivers/ Retorna una lista de conductores para el carro 711
GET /cars/711/drivers/4 Retorna el conductor #4 para el carro 711
GET /cars/711/drivers/4 Retorna el conductor #4 para el carro 711
5. Usar los encabezados HTTP para los formatos de serialización
Ambos, cliente y servidor, necesitan saber qué formato se utiliza para la comunicación. El formato tiene que ser especificado en el encabezado HTTP.
Content-Type define el formato de solicitud.
Accept define una lista de formatos de respuesta aceptables.
Content-Type define el formato de solicitud.
Accept define una lista de formatos de respuesta aceptables.
6. Usar HATEOAS
Hypermedia as the Engine of Application State es un principio que los enlaces de hipertexto se deben utilizar para crear una mejor navegación a través del API.
7. Proporcionar filtrado, clasificación, selección de campos y de paginación para colecciones
8. Versiona tu API
La versión de la API obligatoria. Utilice un número ordinal simple y evitar la notación de puntos tales como 2.5.
Para el ejemplo, estamos utilizando la dirección URL de la API de control de versiones que empiecen con la letra "v"
/blog/api/v1
9. Controlar errores con códigos de estado HTTP
El estándar HTTP proporciona más de 70 códigos de estado para describir los valores de retorno. No todos los necesitamos, perose debe utilizar al menos la cantidad de 10.
10. Habilitar el overriding HTTP method
Algunos servidores proxy sólo admiten métodos POST y GET. Para soportar una API REST con estas limitaciones, la API necesita una forma de reemplazar el método HTT
Se debe usarla personalización del encabezado HTTP X-HTTP-Method-Override en el método POST.
Espero les sirva...
8. Versiona tu API
La versión de la API obligatoria. Utilice un número ordinal simple y evitar la notación de puntos tales como 2.5.
Para el ejemplo, estamos utilizando la dirección URL de la API de control de versiones que empiecen con la letra "v"
/blog/api/v1
9. Controlar errores con códigos de estado HTTP
El estándar HTTP proporciona más de 70 códigos de estado para describir los valores de retorno. No todos los necesitamos, perose debe utilizar al menos la cantidad de 10.
10. Habilitar el overriding HTTP method
Algunos servidores proxy sólo admiten métodos POST y GET. Para soportar una API REST con estas limitaciones, la API necesita una forma de reemplazar el método HTT
Se debe usarla personalización del encabezado HTTP X-HTTP-Method-Override en el método POST.
Espero les sirva...
No hay comentarios.:
Publicar un comentario