• Giovanny Rey Cediel

Diseño de API REST

Actualizado: ago 18

Ya hemos visto las características de una arquitectura REST, a continuación veremos siete lineamientos a tener en cuenta para construir una API que cumpla con esas características.

1. Sustantivos plurales en el URI

El identificador uniforme de recursos, URI, debe estar construido por sustantivos únicamente. Por ejemplo para obtener una lista de clientes, el URI debe ser /clientes. Para obtener un cliente en particular el URI debe ser: /clientes/12. Donde 12 corresponde con el identificador único del registro en la base de datos. Mezclar o cambiar un sustantivo a singular puede causar confusión para los clientes del servicio.

2. No usar verbos en el URI

No se debe utilizar verbos en el URI. Por ejemplo esto no se debería hacer: /getClientes, ya que un API bien construida comunica la acción (el verbo) con el método HTTP de la solicitud. Queda claro que usando el método GET con el URI /clientes, se espera obtener una lista de clientes.


3. Métodos GET que no alteren el estado de los recursos

Los métodos GET deben hacer lo que dicen, obtener recursos. Para manipular recursos están los demás métodos: POST, PUT, PATH y DELETE.

4. Relación de recursos secundarios en el URI

Cuando un recurso esta relacionado con otro recurso, la relación se debe expresar en el URI. Por ejemplo: GET /clientes/12/telefonos indica que se obtendrán todos los teléfonos del cliente 12. GET /clientes/12/telefonos/1 indica que se obtendrá el teléfono 1 asociado al cliente 12.

5. Encabezados HTTP para especificar formato de entrada y salida

En los encabezados HTTP se utilizan varias directivas, entre las cuales están: Content-Type y Accept. Los clientes HTTP utilizan el encabezado Accept para indicar al servidor qué tipos de contenido aceptará. El servidor enviará una respuesta, que incluirá un encabezado Content-Tytpe que le indicará al cliente cuál es el tipo de contenido retornado. Por ejemplo en Spring, un servicio expuesto con el método GET que acepta peticiones en formato JSON, y su vez retorna información en el mismo formato, se especifica de la siguiente manera:

@GetMapping(value = "/clientes", headers = “content-type=application/json, accept=application/json” )

6. Parámetros para filtrar y paginar datos

Los parámetros en el URI se pueden usar para filtrar y paginar datos. Por ejemplo, el URI:

GET /clientes?ciudad=Nashville 

retornará una lista de clientes de la ciudad de Nashville. Si la lista es muy grande, podemos usar parámetros adicionales para indicar desplazamientos y limites, como se muestra en el siguiente URI:

GET /clientes?ciudad=Nashville&offset=10&limit=5 

el cual retornará 5 registros a partir de la posición 10 de la lista de clientes de la ciudad de Nashville.

7. Versionamiento de API

El versionamiento es importante para APIs que son usadas por muchos clientes. La gestión de cambios se apoya en el versionamiento. Por ejemplo, pensemos en el versionamiento semántico. Éste se vale de tres números separados por punto (.) y un tag de estabilidad opcional separado por guión (-). Tal como sigue: X.Y.Z-tag. El primer número (X) define el alcance del proyecto y se incrementa cada vez que se amplíe . El segundo número (Y) se incrementa al adicionar funcionalidades que no amplíen el alcance del proyecto. El tercer número se incrementa con la solución a bugs. Por último el tag de estabilidad, opcional, se puede usar para indicar si la versión ha sido lo suficiente mente probada para ser estable o no. Los incrementos Y.Z deben ser compatibles para el alcance X. En otras palabras, supongamos que un cliente usó el API 1.0.0. Luego de un tiempo adicionamos algunos funciones y corregimos bugs , lo cual produjo el nuevo release: API 1.1.1. Debido a que no afectamos el alcance, el cliente tiene la garantía de actualizar sus desarrollos con el último release sin perder compatibilidad. Generalmente la compatibilidad no se garantiza cuando se amplía el alcance del proyecto. Siguiendo el ejemplo, la versión API 2.0.0, puede implicar perdida de compatibilidad respecto a versiones anteriores.


Ejemplo

A modo de ejemplo, la tabla de abajo muestra los servicios básicos para almacenamiento y recuperación de clientes.


Copyright Giovynet.com 2018 - 2020