API REST

Programación

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, fruitsetc.
  • 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/TodaylowerCamelCase //api.fintech.cp/dailyTransactions/todaysnake_case//api.fintech.cp/daily_transactions/today

Relaciones y recursos

  • Los recursos se tienen one-to-many, many-to-many, many-to-onerelaciones, etc. Mapeo de manera correcta es crucial.

Mapeo de uno a varios

Por ejemplo, Tickets/145/messages/4sugiere una relación de uno a varios entre ticketsy messages. Lo que significa que el 1ticket tiene Nmensajes. El mensaje no es un recurso independiente. No puedes tener /messages/4.

Mapeo de muchos a muchos

Por ejemplo, /usergroups/345/users/56sugiere seleccionar el grupo de usuarios 345 y obtener un usuario con ID 56. Sin embargo, un usuario puede estar en múltiples usergroupsie /usergroups/209/users/56también es válido. En tal caso, para separar el recurso dependiente usersen un punto final separado como /users/56y 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/carsdebe devolver HTTP 201 creado con unlocationencabezado que indique cómo acceder al recurso, por ejemplolocation:api.com/cars/124en 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/124devuelve contenido. Pero también puede regresar 200 OKsi 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