¿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 :)