Header Ads Widget

Ticker

6/recent/ticker-posts

Todo lo que necesita saber sobre el diseño de API REST





Si estudia o crea API de alguna manera, es casi seguro que se encontrará con los términos REST, RESTful o REST-like. A menudo hacemos referencia a REST como una mejor práctica para implementar API. Pero, ¿qué es exactamente la transferencia de estado representacional? ¿Y cuál es la diferencia entre una API REST y una API similar a REST?

Los principios de REST fueron establecidos por Roy Fielding en su disertación de 2000 . Fielding define vagamente REST como un medio para que los clientes y servidores intercambien datos. Un componente clave de la arquitectura REST es que el usuario final no tiene que saber nada sobre la aplicación antes de usarla.

Elementos arquitectónicos de REST

Fielding no menciona formatos de archivo ni especificaciones. En cambio, define REST como el cumplimiento de ciertos elementos y restricciones arquitectónicos específicos.

  1. Cliente-Servidor : las aplicaciones REST deben contener un servidor que administre los datos de la aplicación y defina su estado. El servidor interactúa con un cliente que interactúa con las interacciones del usuario. Cada uno de estos componentes es independiente y se puede modificar de forma independiente.
  2. Sin estado : las aplicaciones REST deben ser apátridas. Todos los datos del estado se gestionan desde el lado del cliente. Una solicitud de la aplicación contiene toda la información necesaria para su procesamiento.
  3. Almacenable en caché : los servidores REST marcan sus datos como almacenables en caché o no. Esto permite que los clientes y las infraestructuras decidan si desean almacenar información en caché o no para mejorar el rendimiento. También les permite deshacerse de información que no se puede almacenar en caché, por lo que se garantiza que los datos que reciben son actualizados y relevantes.
  4. Interfaz uniforme : Tener una interfaz uniforme puede ser la característica más definitoria de REST. Fielding afirma: "La característica central que distingue el estilo arquitectónico REST de otros estilos basados ​​en la red es su énfasis en una interfaz uniforme entre los componentes".
  5. Sistema en capas : los componentes de un sistema REST no pueden ver más allá de su capa. Esto facilita la adición de niveles adicionales de seguridad y equilibrio de carga para mejorar el rendimiento.

Cómo implementar REST

REST se ocupa principalmente de la presentación uniforme de datos como recurso. Una de las piedras angulares del debate “REST vs. RESTful” es mirar solo los puntos finales URI o los comandos HTTP. Sin embargo, esa no es la imagen completa.

Para ilustrarlo, considere un servicio web para modificar una base de datos de comercio electrónico mediante los comandos GET, POST y DELETE.

Una versión de esta aplicación puede tener una única URL que maneja todos los comandos GET y POST. Un usuario puede modificar la base de datos POSTANDO un documento que indique los cambios requeridos.

Se podría agregar un nuevo elemento a la base de datos usando un comando 'NewItem':

POST /inventory HTTP/1.1
 
{
    "NewItem": {
          "name": "new item",
          "price": "9.99",
          "id": "1001"
      }
}    

O podrían consultar la base de datos usando una llamada 'ItemRequest':

POST /inventory HTTP/1.1
{ "ItemRequest": { "id": "1001" } }

Finalmente, puede cambiar o eliminar elementos usando 'ItemDelete' o 'ItemUpdate':

POST /inventory HTTP/1.1
{ "ItemDelete": { "id": "1001" } }

Ninguno de estos enfoques cumple los requisitos de REST. Solo están llamando a funciones usando argumentos para recursos que están almacenados en un documento JSON usando solicitudes HTTP.

Un servicio RESTful tendría un URI para cada artículo del inventario. Publicar un artículo se vería así:

POST /item HTTP/1.1

{
    "Item": {
          "name": "new item",
          "price": "9.99",
          "id": "1001"
      }
}    

Sin embargo, ahí es donde terminan las similitudes. Los comandos GET, POST y DELETE se verían todos muy diferentes. Por ejemplo, recuperar un elemento siempre requeriría un comando GET:

GET /item/1001 HTTP/1.1    

Eliminar una publicación se vería así:

DELETE /item/1001 HTTP/1.1   

Los elementos se pueden modificar usando comandos PUT:

PUT /inventory HTTP/1.1
{ "Item": { "name": "new item", "price": "7.99", "id": "1001" } }

REST trabaja con acciones HTTP específicas, que corresponden a URI específicas. Hay otra razón por la que esta distinción también es esencial.

REST, RESTful y el índice de madurez de Richardson

Cuando los recursos específicos alimentan los URI, hace que una API sea predecible. Los desarrolladores y los usuarios casi pueden visualizar su API incluso si no saben lo que hace.
Incluso si una API no es del todo predecible, aún se puede documentar mediante hipertexto. Esto hace que cada elemento devuelto por una API tenga vínculos para eliminar, actualizar o especificar el nivel de seguridad de un recurso en el inventario.

Por ejemplo, comencemos mirando un código sin recursos. Aquí hay un pequeño código de muestra simple para programar una cita con el médico solo usando HTTP y un método de interacción remota, generalmente basado en la Invocación de procedimiento remoto.

POST /appointmentService HTTP/1.1
[various other headers]

Esto devuelve una respuesta de la base de datos, que muestra los espacios abiertos disponibles en un punto final especificado por un URI. El servidor devolvería algo como esto:

HTTP/1.1 200 OK
[various headers]

El siguiente paso sería reservar una cita utilizando un método similar:

POST /appointmentService HTTP/1.1
[various other headers]

Si todo funciona como debería, verá una respuesta como esta devuelta al punto final de la API.

HTTP/1.1 200 OK
[various headers]

Hasta ahora, este es un sistema estándar de llamada a procedimiento remoto, ya que su código simplemente mueve XML hacia adelante y hacia atrás.

Ahora echemos un vistazo a lo que sucede cuando agregamos recursos, que entregan resultados a puntos finales particulares en lugar de un URI universal.

POST /doctors/mjones HTTP/1.1
[various other headers]


Esto devuelve la misma información esencial pero convierte a cada ranura en un recurso que se puede abordar explícitamente.

HTTP/1.1 200 OK
[various headers]



  
  

El uso de recursos específicos significa devolver las consultas a un espacio en particular.

POST /slots/1234 HTTP/1.1
[various other headers]

Si todo está como debería ser, debería obtener una respuesta similar a la anterior:

HTTP/1.1 200 OK
[various headers]

Esto significa que si la persona que llama a la API necesita acceder a su cita por cualquier motivo, tiene un lugar dedicado para hacerlo.

Desafortunadamente, muchos sitios no cumplen con estos requisitos, pero todavía se les conoce como REST. Esto llevó a Leonard Richardson a crear un modelo para diferenciar los niveles de cumplimiento de REST. Esto se conoce como Índice de Madurez de Richardson .

Los niveles del índice de madurez de Richardson

  • Nivel 0 : exportar una API a través de HTTP con métodos controlados por argumentos
  • Nivel 1 : exportar recursos en lugar de métodos
  • Nivel 2 : uso adecuado de verbos HTTP
  • Nivel 3 : Exportación de hipertexto u objetos para hacer que parte de una API sea detectable

Según el modelo de Richardson, la especificación de Fielding significa que solo las aplicaciones de Nivel 3 califican como REST. Eso significa que muchas aplicaciones que consideramos REST en realidad no lo son.

Casi nada utiliza un enfoque puramente REST. Técnicamente hablando, REST solo se ocupa de los recursos, que se enrutan a URI únicos. Los recursos nunca se agrupan en REST.

Sin embargo, eso no significa que no sea posible. La World Wide Web en sí misma es un ejemplo de una aplicación REST real. Se trata de un cliente y un servidor, por un lado. Por otro lado, no tiene estado, ya que un navegador web no necesita saber lo que está devolviendo.

Echemos un vistazo a una aplicación REST adecuada, para ayudarlo a tener una idea de lo que separa a las API de transferencia de estado representacional del resto. La API de Instagram es compatible con REST.

Comencemos mirando una lista de todas las diferentes acciones para interactuar con una cuenta de usuario.

GET /users/self     Get information about the owner of an access token
GET /users/user-id     Get information about a user
GET /users/self/media/recent   Get most recent media from the user
GET /users/user-id/media/recent    Get most recent media from a user
GET /users/self/media/liked    Get most recent media liked by the user
GET /users/search     Search for a particular user

Como puede ver, esto le permite interactuar con los medios más recientes de un usuario, los medios que le han gustado, comentado e incluso ubicaciones específicas. Este contenido se puede devolver luego a una aplicación separada.

Considere una solicitud a la API de Instagram para fotos de una ubicación en particular.

GET /v1/locations/search?access_token=ACCESS_TOKEN&lat=40.7127&lng=74.0059

Así es como podría verse una respuesta, en formato JSON:

HTTP/1.1 200 OK
{ "meta": { "code": 200 }, "data": [ { "latitude": 40.714198749, "id": "93496093", "longitude": 74.006001183, "name": "John's Pizzeria 278 Bleecker St NY, NY" }, { "latitude": 40.7142, "id": "46371155", "longitude": 74.0064, "name": "Thunderpocalypse 2012" }, { "latitude": 40.714201754, "id": "35932492", "longitude": 74.006397137, "name": "Avenue of the Americas, New York" }, { "latitude": 40.71296389, "id": "1023103828", "longitude": 74.00388611, "name": "Manhattan Municipal Building" }, { "latitude": 40.71322, "id": "92582758", "longitude": 74.003963, "name": "Sleepers Filming Location" }, { "latitude": 40.716833, "id": "97921846", "longitude": 74.005833, "name": "Atera" } ] }

Esto debería darle un ejemplo de cómo la API de Instagram devuelve datos sobre el estado de diferentes recursos a través de la API. También debería ofrecerle una ilustración de cómo esos recursos pueden devolverse a varios puntos finales de la API.

La mayoría de las aplicaciones utilizan algunos de los principios de REST pero no se adhieren a las estrictas especificaciones de Fielding. Esto los hace más similares a REST que a REST propiamente dichos.

DESCANSO vs. REST-Like

Como puede ver en las especificaciones anteriores, no muchos recursos califican como puramente REST. Está bien, ya que REST es más una filosofía o un estilo arquitectónico que un formato concreto.

REST puro es a menudo demasiado difícil de implementar para ser pragmático en muchos proyectos. Los clientes dedican demasiado tiempo, energía y recursos a definir tipos de medios personalizados. Es mucho trabajo lograr que cada punto de datos individual se ajuste a las restricciones arquitectónicas particulares de REST. Como resultado, la mayoría de las aplicaciones de REST en el mundo real son similares a REST .

Eso no impide que las personas describan cualquier servicio orientado a recursos basado en URL como REST. Es una cuestión de semántica, de verdad. El lenguaje evoluciona y también las definiciones.

La tendencia a dividir los pelos sobre si una API es REST o no muestra que estás pensando más como un desarrollador que como un usuario de la API, lo cual es un error. Es probable que a un consumidor de API le importe menos si una API se adhiere a la visión purista de Roy Fielding. Son de los que debe preocuparse si desea que su API tenga éxito.

En el pasado, nos referimos a las API similares a REST como REST pragmático . Para garantizar que su API siga las mejores prácticas de REST sin preocuparse demasiado por los puntos finales y los recursos de URI, aquí hay algunas mejores prácticas de API similares a REST:

Principios del diseño tipo REST

  1. Fácil de usar
  2. Apátrida
  3. Seguro
  4. Independiente de la plataforma
  5. En continua evolución
  6. Consistencia
  7. Flexibilidad
  8. Documentación útil

APIS y HATEOAS tipo REST

Según Roy Fielding, solo las API que utilizan hipervínculos e hipermedia califican como verdaderas aplicaciones REST . Eso significa que las aplicaciones que utilizan HATEOAS (Hypermedia as the Engine of Application State) son verdaderamente dispositivos REST. Sin embargo, muchas API de uso generalizado no utilizan hipermedia, incluidas las API de Facebook y Twitter. Claramente, se puede argumentar que HATEOAS es innecesario para tener una API exitosa.

Por un lado, muchos usuarios finales terminan sin utilizar HATEOAS. Los usuarios ocasionales estarán contentos de descubrir los puntos finales que necesitan a través de la documentación en lugar de los enlaces proporcionados en una respuesta.

También hay una falta de consenso sobre en qué formato se debe implementar HATEOAS. JSON-LD es útil para adjuntar a API existentes, por ejemplo. Collection-JSON y JSON API son útiles para tratar con listas.

Esta falta de estándares dificulta la implementación de API estandarizadas, que es una de las razones de la arquitectura REST y similar a REST en primer lugar.

HATEOAS tampoco es ideal para transmitir datos, ya que los lee como otro tipo de medio genérico. Esto significa que debe delinear la diferencia a través de la documentación, lo que complica innecesariamente el desarrollo.

Lea también: 8 consejos para diseñar API REST de calidad

REST vs API similares a REST: veredicto final

Roy Fielding estableció las reglas básicas del DESCANSO en el cambio de siglo. Evidentemente, Internet ha evolucionado enormemente en los últimos 20 años. No teníamos iOS o Android, por un lado. Ni siquiera teníamos Google Chrome en ese momento.

Sin embargo, muchos de los principios establecidos en la visión de Fielding siguen siendo relevantes y válidos. Son buenas pautas para disparar, pero no debes preocuparte demasiado por eso. El índice de madurez de Richardson es más útil para el desarrollo real. Debe aspirar a alcanzar el nivel 3 del índice de madurez si aún no lo ha hecho.

Publicar un comentario

0 Comentarios