Historia
REST son las siglas en inglés de Re presentational S tate T ransfer protocol. Roy Fielding definió REST en su tesis doctoral en 2000.
¿Qué es una API REST?
REST fue desarrollado para proporcionar una interfaz uniforme para
- Identificación de recursos
- Manipulación de recursos
- Mensajes autodescriptivos
- Uso de Hypermedia como motor del estado de la aplicación (HATEOS)
Mejores prácticas
Lo esencial
Método || //api.co/v2/cars || //api.co/v2/cars/1234
- OBTENER || Lista de todos los coches || Recuperar un coche individual
- POST || Crea un coche nuevo || Error
- PUT || Reemplazar colecciones de automóviles || Reemplazar el auto con id 1234
con uno nuevo
- BORRAR || Eliminar todos los coches || Eliminar coche con id 1234
Tenga en cuenta que mientras las operaciones PUT, ya sea cliente o servidor, pueden generar identificaciones
Los sustantivos son buenos Los verbos son malos
- Use sustantivos para referirse a recursos como
cars
,fruits
etc. - Use verbos para declaraciones de acción
convertMilesToKms
,getNutritionalValues
¿Singular o plural?
Use la gramática correcta para la declaración
Evitar/person/145
Prefiero/people/154
Asumir que devuelve la persona número 154 de la lista de personas
Casos de uso
¡Utilice cualquiera de los siguientes patrones y sea coherente!
Caso StylesExample UpperCamelCase //api.fintech.cp/DailyTransactions/Today
lowerCamelCase //api.fintech.cp/dailyTransactions/today
snake_case//api.fintech.cp/daily_transactions/today
Relaciones y recursos
- Los recursos se tienen
one-to-many
,many-to-many
,many-to-one
relaciones, etc. Mapeo de manera correcta es crucial.
Mapeo de uno a varios
Por ejemplo, Tickets/145/messages/4
sugiere una relación de uno a varios entre tickets
y messages
. Lo que significa que el 1
ticket tiene N
mensajes. El mensaje no es un recurso independiente. No puedes tener /messages/4
.
Mapeo de muchos a muchos
Por ejemplo, /usergroups/345/users/56
sugiere seleccionar el grupo de usuarios 345 y obtener un usuario con ID 56. Sin embargo, un usuario puede estar en múltiples usergroups
ie /usergroups/209/users/56
también es válido. En tal caso, para separar el recurso dependiente users
en un punto final separado como /users/56
y proporcionar enlace de recursos en/usergroups/209/users/56
Parámetros API
- RUTA : requerida para acceder al recurso Ej.
/cars
,/fruits
- Parámetros de consulta :filtro opcional de la lista Ej.
/cars?type=SUV&year=2010
- Cuerpo : Lógica específica del recurso. Consulta de búsqueda avanzada. A veces puede tener tanto Query como body.
- Encabezado : debe contener datos globales o de toda la plataforma. Por ejemplo, parámetros de clave API, claves cifradas para autenticación, información del tipo de dispositivo, por ejemplo, dispositivo móvil o de escritorio o punto final, tipo de datos del dispositivo, por ejemplo, xml o json. Utilice el encabezado para comunicar estos parámetros
Códigos de estado HTTP
Utilice códigos de estado correctos
Códigos Significado1xx Solicitud recibida y comprendida.2xx Se recibió, comprendió y solicitó la acción solicitada por el cliente.3xx El cliente debe tomar medidas adicionales para completar la solicitud. La mayoría de estos códigos de estado se utilizan en URL Redirection.4xxIntended para situaciones en las que parece que el error fue causado por el cliente.5xxEl servidor no cumplió con una solicitud.
¡Poco más sobre 2xx !
- 201 Recurso creado. POST
/cars
debe devolver HTTP 201 creado con unlocation
encabezado que indique cómo acceder al recurso, por ejemplolocation
:api.com/cars/124
en el encabezado
202 - Aceptado
Use esto si la tarea es enorme para ejecutar. Dígale al cliente que ha aceptado la solicitud y la procesará / está procesando No se devuelve la carga útil
204 - Sin contenido
Se usa cuando se elimina No DELETE cars/124
devuelve contenido. Pero también puede regresar 200 OK
si la API tiene la intención de enviar el recurso eliminado para su posterior procesamiento.
¡Los peligrosos recursos 5xx !
- 500 Error interno del servidor
- 504 Tiempo de espera de puerta de enlace. El servidor no recibió una respuesta oportuna
4xx menos conocido sugiere que está pasando un parámetro incorrecto. También puede pasar información incorrecta. P.ej
DELETE /cars/MH09234
returns 4xx
or message Expecting int car id /car/id got string car/MH09234