¿Cómo diseñar una API Rest?
Muchas veces nos preguntamos como diseñar una API, ¿existe un estándar? ¿hay algún tipo de clean API? En este artículo intentaremos dar respuesta a estas preguntas, pero sobre todo a darte los consejos y conceptos a tener en cuenta para que la próxima vez que diseñes una API Rest, lo hagas como todo un experto ;)
Pero, ¿Qué es una API Rest?
El término REST (Representational State Transfer) se originó en el año 2000. Un servicio REST no es una arquitectura software, sino un conjunto de restricciones con las que podemos crear un estilo de arquitectura software, la cual podremos usar para crear aplicaciones web respetando HTTP.
¿Y una API?, El término API es una abreviatura de Application Programming Interfaces, que en español significa interfaz de programación de aplicaciones. Se trata de un conjunto de definiciones y protocolos que se utiliza para desarrollar e integrar el software de las aplicaciones, permitiendo la comunicación entre dos aplicaciones de software a través de un conjunto de reglas.
Verbos HTTP:
Estos son los verbos que se utilizan en el diseño de API Rest, importante conocerlos para poder realizar un buen diseño, solo definiremos los más usados:
GET - Para obtener recursos
PUT - Para actualizar recursos
POST - Para guardar recursos
DELETE - Para eliminar recursos
OPTIONS
HEAD
TRACE
CONNECT
¿Qué es la seguridad?
Otro tema a tener en cuenta cuando queremos diseñar una API, es sus seguridad, es algo muy importante, y en la que mucha gente no hace hincapié, tanto como conocer el concepto de idempotencia.
¿Y cuando es seguro un verbo HTTP?
Cuando la ejecución repetida de un recurso utilizando ese verbo no tienen ningún estado en el servidor, (estado no es solo la BBDD sino también la memoria). Los servicios no deberían almacenar estado.
Por ejemplo si hago un petición N veces con GET el estado del servidor se mantiene igual, es seguro.
Si hago una petición N veces con POST el estado del servidor cambia, NO es seguro.
Por ello el concepto de idempotencia es muy importante, ¿Qué es?
Idempotencia
Cuando se invoca repetidamente el mismo recurso con los mismos parámetros tiene el mismo efecto en el estado del servidor si se ejecuta 1 o N veces. No significa que la respuesta sea la misma.
POST NO es idempotente.
PUT SI es idempotente.
Aquí te dejo una tabla con los verbos HTTP

¿Cuándo usar cada uno?
GET
Consulta de datos
No se modifica el estado del servidor
Caché
POST
Alta de nuevas entidades
No saber la URI donde va a residir
Sobre la URI del recurso padre
PUT
Creación de recursos en la URI especificada
Modificación de recursos
Operaciones deben ser idempotentes
DELETE
Eliminar recursos
Idempotente
¿Por qué la idempotencia?
- HTTP no asegura la entrega, ¿y si falla? Solución: reintentos.
- Para evitar la duplicidad.
Imaginemos que estamos en Amazon y damos de alta un pedido, la petición falla, la volvemos a hacer, y falla y a la tercera funciona. Puede que el pedido se haya creado varias veces y no podemos cobrarle 2 o 3 veces al cliente por el mismo pedido. Con PUT esto se soluciona, dado que por muchas peticiones que se realicen solo va a crear un único recurso y luego actualizar el mismo, por eso se dice que es idempotente, porque no modifica el estado del servidor.
Muchas veces no podemos conocer el identificador y no podemos usar PUT y usamos POST. ¿Solución? Recursos virtuales.
¿Y qué son los recursos virtuales?
Consiste en descomponer la petición en 2 pasos. Primero un POST para pedir un identificador, ya sea aumentando la clave primaria, creando un hash, etc. Esto aunque falle, en el momento que funcione nos dará un identificador válido. Y luego realizamos el PUT con ese identificador, que por mucho que falle será idempotente.
El principio HATEOAS
Ahora vamos a ver otro principio muy importante y que poca gente conoce (creo)
Hypermedia As The Engine Of Application State
La aplicación del principio HATEOAS permite que la interfaz de un servicio REST pueda modificarse siempre que se requiera, lo que constituye una ventaja fundamental de esta arquitectura frente a otras, como las basadas en SOAP
Consejo:
- Una API a partir de un recurso raíz debe poder ser recorrida sin documentación. Esto último es un gran consejo, y nos indica un gran diseño detrás de la API.
Niveles de madurez REST:
Nivel 0: HTTP como capa de transporte. (SOAP)
Nivel 1: Orientamos el diseño a recursos
Nivel 2: Uso correcto de verbos HTTP
Nivel 3: Añadimos controles hypermedia
Lo ideal es estar al menos en el Nivel 2.
Beneficios de estar en el nivel 2:
Aumenta la interoperabilidad de la API
Ahorramos documentación (no siempre hace falta NO documentar)
Reducir cantidad de datos devuelta por el servidor
Permite definir flujos de negocio
Bien, es cierto, que con este artículo solo probablemente no construyas una API, pero si son las cosas básicas a tener en cuenta a la hora de diseñarla, e incluso a la hora de trabajar con verbos HTTP y recursos REST, ya os acordareis de la idempotencia...
Espero que te haya gustado, nos vemos en la próxima :)