5.3 KiB
title | localeTitle |
---|---|
Rest API Design | Diseño API de descanso |
Historia
RESTO significa Re protocolo T ransferencia S tate de presentación. Roy Fielding definió a REST en su tesis doctoral en el año 2000.
¿Qué es?
REST fue desarrollado para proporcionar una interfaz uniforme para
- Identificando recursos
- Manipulación de recursos.
- Mensajes auto descriptivos
- Uso de Hypermedia como el motor del estado de la aplicación (HATEOS)
Mejores prácticas
- #### Fundamentos
| Método | http://api.co/v2/cars | http://api.co/v2/cars/1234 |
| --- | --- | --- | | GET | Listar todos los coches | Recuperar un coche individual | | POST | Crear un coche nuevo | Error | | PUT | Reemplazar colecciones de autos con una nueva | Reemplazar el coche con id 1234 | | BORRAR | Borrar todos los coches | Eliminar coche con id 1234 |
Tenga en cuenta que mientras que las operaciones PUT, el cliente o el servidor pueden generar ID
-
Los sustantivos son buenos Los verbos son malos
-
Usa sustantivos para referir recursos como
cars
,fruits
, etc. -
Use verbos para declaraciones de acciones
convertMilesToKms
,getNutritionalValues
-
¿Singular o plural?
Usa la gramática correcta para la declaración.
Evitar
/person/145
Prefiero
/people/154
Supongamos que se devuelve 154a persona de la lista de personas -
Usar carcasa
¡Usa cualquiera de los siguientes patrones y sé consistente!
| Estilos de caja | Ejemplo | | ------------- | ------------- | | UpperCamelCase |
http://api.fintech.cp/DailyTransactions/Today
| | lowerCamelCase |http://api.fintech.cp/dailyTransactions/today
|
| snake_case |http://api.fintech.cp/daily_transactions/today
| -
Relaciones y recursos
-
Los recursos pueden tener relaciones de
one-to-many
, demany-to-many
, demany-to-one
, etc. El mapearlos correctamente es crucial. -
Mapeo uno a muchos
Por ejemplo,
Tickets/145/messages/4
sugiere una relación de uno a varios entretickets
ymessages
. Significado de1
ticket tieneN
mensajes. El mensaje no es un recurso independiente. No puedes tener/messages/4
. -
Muchos a muchos mapeos
Por ejemplo,
/usergroups/345/users/56
sugiere seleccionar 345o grupo de usuarios y obtener usuario con id 56. Sin embargo, un usuario puede estar en variosusergroups
es decir,/usergroups/209/users/56
también es válido. En tal caso, para separar a losusers
recursos dependientes en un punto final separado como/users/56
y proporcionar enlaces de recursos en/usergroups/209/users/56
-
Parámetros API
-
RUTA : requerida para acceder al recurso Ej.
/cars
,/fruits
-
Parámetros de consulta : opcional filtrar 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 consulta como cuerpo.
-
Encabezado : Debe contener datos globales o de plataforma amplia. Por ejemplo, parámetros de clave API, claves encriptadas para autenticación, información de 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
Usa códigos de estado correctos
| Codigos Significado | | ------------- |: -------------: | | 1xx | Solicitud recibida y entendida. | | 2xx | Acción solicitada por el cliente fue recibida, entendida y solicitada. | | 3xx | El cliente debe tomar medidas adicionales para completar la solicitud. La mayoría de estos códigos de estado se utilizan en la redirección de URL. | | 4xx | Destinado a situaciones donde parece que el error fue causado por el cliente. | | 5xx | El servidor no pudo completar una solicitud. |
¡Poco más en 2xx !
-
201 Recurso creado. POST
/cars
debe devolver HTTP 201 creado con el encabezado delocation
indica cómo acceder al recurso Por ejemplo,location
:api.com/cars/124
en el encabezado -
202 - Aceptado
Use esto si la tarea es enorme para ejecutar. Dígale al cliente, ha aceptado la solicitud y será / es proceso / procesamiento No se devuelve ninguna carga
-
204 - Sin contenido
Se usa cuando se eliminan los
DELETE cars/124
No devuelve contenido. Pero también puede devolver200 OK
si la API intenta enviar el recurso eliminado para su posterior procesamiento.¡Los peligrosos recursos 5xx !
-
Error interno del servidor 500
-
504 Tiempo de espera de puerta de enlace. El servidor no recibió una respuesta oportuna
Menos conocido 4xx sugiere que está pasando un parámetro incorrecto. También puede pasar información que es incorrecta. P.ej
DELETE /cars/MH09234
devuelve
4xx
o mensajeExpecting int car id /car/id got string car/MH09234
Otras lecturas
Cómo diseñar excelentes APIs - Parse Developer Day 2013
El interminable debate sobre el diseño de la API REST por Guillaume Laforge