Saltar al contenido principal

Que es REST?

  • REST es un acronimo de REpresentational State Transfer
    • En español: Transferencia de estado representacional
    • En el 2000 Roy Fielding lo presento en una tesis universitariay desde entonces se ha convertido en el enfoque más usado para construir APIs basadas en la web
    • API: Application Programming Interfaces
  • REST no es un protocolo o un estandar
    • Es un patrón de diseño de arquitectura de software.
    • Se implementa durante el desarrollo de software.
    • Como otros patrones de diseño, REST se guia en principios y restricciones.
    • Los servicios que cumplen con estos requisitos pueden ser llamados RESTful.

Los seis principios del REST​

  1. Interfaz uniforme (Uniform Interface)
    1. Aplicando el principio de generalidad, podemos simplificar la arquitectura del sistema y mejorar la visibilidad de las interacciones. Restricciones multiples de arquitectura ayuda a obtener una interfaz uniforme y una guia del comportamiento de la misma.
      1. Principio de generalidad: El principio de generalidad en ingeniería de software, según la guía de G. Shute, destaca la importancia de diseñar sistemas sin restricciones artificiales o limitaciones innecesarias, permitiendo que el software sea más adaptable y duradero. Este principio está estrechamente relacionado con la anticipación al cambio, ya que al evitar restricciones innecesarias, el software puede adaptarse más fácilmente a futuras modificaciones o necesidades imprevistas.
    2. Las siguientes 4 limitaciones pueden asegurar una interfaz REST uniforme:
      1. Identificación de recursos: La interfaz debe identificar de forma unica cada recurso involucrado en la interacción entre el cliente y el servidor.
      2. Manipulación de recursos a traves de representaciones: Los recursos deben tener representaciones uniformes en el response del servidor.
        1. El cliente debe usar esas representaciones para modificar el estado del recurso en el servidor.
      3. Mensajes autodescriptivos: Cada representación de los recursos debe tener suficiente información para describir como procesar el mensaje.
        1. Ademas de proveer información sobre que acciones adicionales el cliente puede llevar a cabo en ese recurso.
      4. Hypermedia como engine del estado de la aplicación: El cliente solo tiene el URI inicial de la aplicación.
        1. El cliente debe acceder de forma dinamica a los recursos e interacciones mediante el uso de hyperlinks.
    3. En resumen, REST define una interfaz uniforme y consistente para realizar interacciones entre cliente y servidor.
  2. Cliente-Servidor
    1. Esta arquitectura fuerza la separación de intereses, la cual permite al cliente y al servidor escalar de forma independiente.
    2. Al separar la interfaz del cliente de la del servidor, mejoramos tanto la portabilidad y la escalabilidad.
  3. Stateless
    1. Statelessness significa que cada request desde el cliente al servidor debe contener toda la info necesaria para entender y completar la request.
    2. No debe usar información previamente almacenada en algún contexto del servidor.
    3. Por esta razon, es responsabilidad total del cliente mantener toda la información sobre el estado de la sesión.
  4. Cacheable
    1. La restricción de ser cacheable requiere que una respuesta se etiquete de forma implícita o explícita como cacheable o no cacheable.
    2. Si la respuesta es cacheable, la aplicación cliente puede reutilizar los datos de la respuesta más adelante para solicitudes equivalentes y durante un período de tiempo especificado.
  5. Código on Demand (Opcional)
    1. REST permite a clientes la funcionalidad de ser extendido por descarga o código a traves de applets o scripts.

Que es un Recurso?​

  • Es una abstracción de información.
  • Cualquier información que se le pueda asignar un nombre es un recurso.
    • Puede ser:
      • Un documento
      • Una imagén
      • Un servicio temporal.
      • Una colección de otros recursos.
      • Un objeto no virtual (e.g una persona).
  • El estado de un recurso en un intervalo de tiempo dado se conoce como representación de un recurso y consiste en:
    • Datos
    • Metadata para decribir los datos anteriores
    • Links de Hypermedia que ayudan a los clientes a transicionar al siguiente estado.
  • Una API REST consiste en un conjunto de recursos interconectados. Este conjunto de recursos se conoce como el modelo de recursos de la API REST.

Indentificador de recursos​

  • REST usa identificadores de recursos para identificar cada recurso involucrado en las interacciones entre los componentes cliente y servidor.
  • En REST, cada recurso (usuario, pedido, producto) tiene su propia dirección (identificador único), que normalmente es una URL.
    • https://api.ejemplo.com/users/123 → Identifica al usuario con ID 123.
    • https://api.ejemplo.com/orders/456 → Identifica al pedido con ID 456.
    • https://api.ejemplo.com/products/789 → Identifica al producto con ID 789.
    • https://api.ejemplo.com/users/123/posts → Identifica todos los posts del usuario 123.

Hypermedia​

  • El formato de datos de una representación se conoce como media type.
  • Estos indican qué tipo de datos se están enviando o recibiendo.
    • application/json → Para enviar o recibir datos en formato JSON (muy común en APIs REST).
    • application/xml → Para datos en formato XML.
    • text/html → Para contenido HTML.
    • text/plain → Para texto plano.
    • application/pdf → Para documentos PDF.
    • image/png → Para imágenes PNG.
    • Etc
  • Una api RESTful luce como hypertexto, cada unidad de información direccionable contiene una dirección:
    • Explicita: Links o ids
    • Implicita: Derivada de un media type u otra estructura.
  • Hipertexto (o hipermedia) significa la presentación simultánea de información y controles, de modo que la propia información se convierte en el medio a través del cual el usuario (o una máquina) obtiene opciones y selecciona acciones.
  • El hipertexto no necesita ser HTML (o XML o JSON) en un navegador. Las máquinas pueden seguir enlaces siempre que entiendan el formato de los datos y los tipos de relaciones.

Autodescriptivo​

  • Una representación de un recurso debe ser autodescriptiva.
    • El cliente no necesita saber si un recurso es un empleado o un dispositivo, debe actuar basado en el media type asociado al recurso.
  • En la practica, se crean un monton de media types personalizados, usalmente un media type asociado a un recurso.
  • Cada media type define un modelo de procesamiento por defecto.
    • Por ejemplo HTML define el renderizado a traves de hipertexto y el comportamiento del navegador.
  • Los Media Types no tienen relación con los metodos de recursos GET/PUT/POST/DELETE, es decir, el media type describe cómo interpretar y usar el contenido, pero no fuerza un método HTTP específico

Ejemplo​

Considera el siguiente recurso REST que representa una entrada de blog con enlaces a recursos relacionados en una API REST basada en HTTP.

Este recurso contiene la información necesaria sobre la entrada del blog, así como los enlaces hipermedia a los recursos relacionados, como el autor y los comentarios.

Los clientes pueden seguir estos enlaces para descubrir información adicional o realizar acciones.

{
  "id": 123,
  "title": "What is REST",
  "content": "REST is an architectural style for building web services...",
  "published_at": "2023-11-04T14:30:00Z",
  "author": {
    "id": 456,
    "name": "John Doe",
    "profile_url": "https://example.com/authors/456"
  },
  "comments": {
    "count": 5,
    "comments_url": "https://example.com/posts/123/comments"
  },
  "self": {
    "link": "https://example.com/posts/123"
  }
}

Metodos de recursos​

  • Estos metodos son usados para ejecutar una transición entre dos estados de un recurso.
  • Mucha gente asume que "crear es POST", "obtener es GET", "actualizar es PUT", etc., pero eso no está definido ni obligado por REST según Roy Fielding.
  • Lo importante para REST es que la interfaz sea uniforme y coherente, no que uses obligatoriamente un método específico para cada acción.
  • Por ejemplo si necesitas usar un POST para actualizar un recurso en vez del metodo común PUT, está bien, aun asi la aplicación sera RESTful

Debemos ingresar a una API REST sin ningún conocimiento previo más allá de la URI inicial y un conjunto de media types estandarizados apropiados (que cualquier cliente que use la API pueda entenderlos).

A partir de ahí, todas las transiciones de estado de la aplicación deben ser guiadas por las opciones que el servidor provee en las representaciones recibidas, o por las acciones que el usuario realice sobre esas representaciones.

Las transiciones pueden estar determinadas (o limitadas) por el conocimiento del cliente sobre los media types y los mecanismos de comunicación de recursos, los cuales pueden mejorar dinámicamente (por ejemplo, mediante código bajo demanda).

Si esto falla, significa que la interacción está siendo dirigida por información externa (out-of-band) en lugar de por hipertexto.

En resumen:

  • El cliente solo debería necesitar la URI inicial y saber interpretar los media types.
  • Todo el flujo de navegación/acciones debería surgir de los enlaces e información que el servidor envía en cada respuesta (hipermedia).
  • Si el cliente depende de instrucciones externas (documentación, reglas fuera del sistema), entonces no se está aprovechando bien REST.
    • Esto es el principio de HATEOAS (Hypermedia as the Engine of Application State).

REST y HTTP no son lo mismo.​

REST != HTTP

En su tesis, Roy Fielding no mencionó ninguna directiva de implementación, ni siquiera una preferencia por un protocolo específico o por HTTP.

Mientras respetemos los seis principios fundamentales de REST, podemos llamar a nuestra interfaz RESTful.

👉 REST no está atado a HTTP (aunque normalmente se usa con HTTP).

👉 Lo importante es seguir los principios arquitectónicos de REST (como stateless, interfaz uniforme, cacheable, etc.).

👉 Si se cumplen esos principios, la interfaz puede considerarse RESTful, sin importar el protocolo o la tecnología.