Qué es RESTful

Vemos por ahí varias veces las palabras REST y RESTful. Vamos a entender un poco antes de comenzar.

REST (Representational State Transfer) Es un concepto o estilo arquitectural para construcción de APIs.
- Define un conjunto de principios que guían la comunicación entre sistemas, como:
- Comunicación stateless (sin estado).
- Uso de métodos (Verbos) HTTP adecuados (GET, POST, PUT, DELETE, etc.).
- Representación de recursos a través de URIs.
- Soporte a diferentes formatos de datos (JSON, XML, etc.).
- HATEOAS (Hypermedia as the Engine of Application State) como un principio avanzado.
RESTful Se refiere a una implementación práctica y adherente a los principios REST.
- Una API es llamada de RESTful cuando sigue los principios REST correctamente, como:
- Utilizar URIs claras y descriptivas para representar recursos.
- Operar de forma stateless.
- Usar los métodos HTTP de forma consistente (ej.: GET para lectura, POST para creación, etc.).
- Retornar códigos de estado HTTP apropiados (ej.: 200 OK, 404 Not Found).

REST es el concepto/estilo arquitectural. RESTful es la aplicación práctica de ese concepto en APIs. Si una API no sigue los principios de REST, no puede ser llamada de RESTful.

Puedes implementar una API basada en conceptos REST sin ser completamente RESTful. Esto ocurre cuando la API utiliza algunos de los principios REST, pero no los implementa de forma correcta o completa.

Ejemplos de APIs REST no RESTful

Métodos HTTP usados incorrectamente: Una API que usa apenas POST para todas las operaciones (lectura, creación, actualización y exclusión) no es RESTful, aunque use URLs y JSON. Ejemplo:
```
POST /getUsers
POST /createUser
POST /deleteUser
```

Para ser RESTful, debe usar métodos adecuados (GET, POST, PUT, DELETE).

Ausencia de URIs claras y consistentes: URLs que no representan recursos de forma intuitiva, como:
```
/action?operation=getUser&id=1
```
Un enfoque RESTful sería:
```
/users/1
```
Mantener estado en el servidor: APIs que dependen de sesiones en el servidor o almacenan informaciones de contexto sobre el cliente entre las peticiones rompen el principio de ser stateless.
Ignorar códigos de estado HTTP: Retornar siempre 200 OK con un mensaje de error en el cuerpo, en vez de usar códigos apropiados como 404 Not Found o 500 Internal Server Error.

Terminología

Verbos o HTTP Methods: GET PUT, POST DELETE
Messages - El payload de una acción
URI - Uniform Resource Identifier.
- Es un string único que identifica un recurso.
- Puede representar cualquier cosa: un documento, una imagen, una persona, o hasta un concepto abstracto.
- Incluye dos tipos principales:
  - URL (Uniform Resource Locator) – Localiza un recurso.
  - URN (Uniform Resource Name) – Nombra un recurso de manera única, independientemente de su ubicación.
- Ejemplo:
  - https://example.com/document (URL, pues localiza el recurso).
  - urn:isbn:0451450523 (URN, pues nombra un libro por el ISBN, sin informar dónde encontrarlo).
URL - Uniform Resource Locator. Es un subconjunto de URI.
- Es un subconjunto de URI.
- Siempre describe la ubicación de un recurso en internet.
- Incluye informaciones como:
  - El esquema/protocolo (ej.: http, https, ftp).
  - La dirección del recurso (ej.: example.com).
  - Opcionalmente, camino, parámetros y fragmentos (ej.: /page?id=10#section).
- Ejemplo de URL:
  - https://example.com/document (informa cómo y dónde acceder al documento).

Toda URL es una URI, pero no toda URI es una URL.

Idempotencia en RESTful se refiere a una propiedad de los métodos HTTP donde múltiples llamadas del mismo método con los mismos parámetros/resultados no alteran el estado del recurso más allá del efecto inicial. En otras palabras, puedes llamar la misma operación varias veces sin obtener resultados diferentes o causar efectos colaterales adicionales.
- Operaciones GET deben ser consideradas idempotentes pues no alteran nada en el servidor.
Stateless significa que no guarda el estado y cada petición enviada por un cliente a un servidor es independiente y no depende de informaciones mantenidas por el servidor sobre peticiones anteriores. Esto es una característica fundamental de APIs RESTful y del protocolo HTTP.
- El hecho de no guardar nada solamente procesar y devolver siempre hace escalable y simple.
- Cada petición contiene todas las informaciones necesarias para ser procesada. Ejemplo: Autenticación es generalmente enviada con cada petición, por medio de un token o encabezado Authorization.
HATEOAS (Hypermedia As The Engine of Application State) es un principio de la arquitectura RESTful que describe cómo un cliente interactúa con un servidor a través de hipermedia. La idea central es que las respuestas de la API deben proporcionar links para otros recursos o acciones posibles, permitiendo que el cliente navegue por el sistema sin necesitar conocer todos los detalles de su funcionamiento.
- En vez de que el cliente necesite conocer todas las URLs disponibles para interactuar con la API, las respuestas de la API deben incluir links que indiquen cuáles otras operaciones pueden ser hechas a partir de ese punto. Esto crea una forma de navegación dinámica dentro de la aplicación, sin que el cliente tenga que hacer suposiciones sobre las rutas.
```
GET /users/1
```
El servidor responde con los datos del usuario, incluyendo links para acciones relacionadas:
```
{
  "id": 1,
  "name": "David",
  "email": "[email protected]",
  "links": [
    { "rel": "self", "href": "/users/1" },
    { "rel": "orders", "href": "/users/1/orders" },
    { "rel": "update", "href": "/users/1/update" },
    { "rel": "delete", "href": "/users/1/delete" }
  ]
}
```

Ejemplos de APIs REST no RESTful​

Terminología​

Ejemplos de APIs REST no RESTful

Terminología