Pronoide: Diseño de un api ReST (II)

Continuamos la serie sobre apis ReST. En el anterior post vimos el papel que tiene el protocolo HTTP y el significado de los métodos, así como ejemplos de las urls más sencillas. Con estos rudimentos podemos construir nuestra api, en un ejemplo en el que el recurso serán los clientes en una aplicación de gestión.

El recurso

Los recursos cliente de nuestro ejemplo tendrán las siguientes propiedades (a modo de muestra)

id: numérico, es un identificador único para cada cliente
nombre, cadena de texto
direccion, cadena de texto
telefono, cadena de texto

El api

Antes de definir un api debemos conocer lo que se esperan las aplicaciones clientes de nuestro servicio y cuales son los requisitos de la aplicación que lo publica. Vamos a suponer que en nuestro caso es necesario un mantenimiento básico de los datos de los clientes, con las siguientes funcionalidades:

Generación de listados de clientes
Búsqueda de un cliente
Alta de un nuevo cliente
Modificación de un cliente
Baja de un cliente

-Nada que ver aquí, es solo un CRUD

GET /clientes

Devuelve el contenido del directorio ‘clientes’. Aquí hay una idea importante: lo que debe devolver una petición GET será lo contenido en la última carpeta de la ruta si no se adjunta un identificador. ¿Y si hay muchos clientes? Pues mientras no filtremos los resultados deberán devolverse todos. Más adelante hablaremos de cómo debe expresarse el filtrado de resultados en un api ReST

Vemos que al solicitar clientes con GET nos envían un documento JSON con la representación del estado actual de los clientes en el servidor.

-¿Asi que eso es lo que significa representational state transfer?

GET /clientes/{id}

Devuelve el recurso contenido en el directorio ‘clientes’ cuyo identificador es ‘id’. ¿Y si no existe un recurso con ese identificador? Otro punto importante aquí: todas las respuestas que de el servidor deben incluir el código de respuesta HTTP adecuado. En este caso debería ser 404 NOT FOUND en lugar de un 200 OK.

Podría pensarse que para solicitar un único cliente debiera ser ‘GET /cliente/{id}’ pero esto no es así. El protocolo HTTP habla de recursos que están en directorios y los clientes están en ‘clientes’. Es una regla: los directorios guardan muchos recursos, los directorios están en plural. Es más: la petición ‘GET /clientes/{id}’ ha de interpretarse como ‘entra en el directorio clientes y localiza el recurso cuyo id es el indicado’.

POST /clientes

Insertará un recurso nuevo en el directorio ‘clientes’. De nuevo nos encontramos con asuntos destacables. El nuevo recurso deberá adjuntarse como contenido en el cuerpo de la petición HTTP, en el formato que el servidor espere o soporte. Como respuesta a una petición post es buena idea entregar el recurso tal y como ha quedado en el servidor, su id o un enlace a él.

PUT /clientes/{id}

Localiza el recurso cuyo id se indica en la ruta y lo sustituye por el que se haya proporcionado con la petición. Si el recurso no existiera es elección del servidor el devolver un 404 o crear un nuevo recurso.

En la petición el identificador del cliente a sustituir está en la ruta. En este ejemplo tambien lo vemos en el documento json del cuerpo. Esto es habitual, ya que las aplicaciones cliente suelen generar el json a partir de objetos en memoria y no se molestan en eliminar propiedades no solicitadas. El servidor utilizará solo el id de la ruta y deberá ignorar completamente cualquier otro.

PATCH /clientes/{id}

PATCH fue añadido a HTTP en 2010. Es similar a PUT salvo que mientras PUT sustituye un recurso por otro PATCH modifica el existente. Esto implica que en una petición PATCH puede adjuntarse una representación parcial del recurso que incluya únicamente los valores que han de cambiar.

En la petición el identificador del recurso forma parte de la ruta (el recurso identificado con '25' del directorio 'clientes') y en el cuerpo de la petición solo se indica las propiedades que cambian. En la respuesta (y esto es opcional) se incluye el recurso entero tal y cómo ha quedado.

DELETE /clientes/{id}

Esta petición solicita la eliminación del recurso identificado por ‘id’, que está en el directorio ‘clientes’. Si el recurso se ha podido eliminar la respuesta será un 200 OK si queremos indicar algo al cliente (en el body de la respuesta) o 204 NO CONTENT si la simple respuesta 2XX basta. Si el recurso no existiera debería devolverse un 404 NOT FOUND.

Una petición DELETE que no incluya el identificador del recurso debería afectar a todos los recursos del directorio, es decir: ‘DELETE /clientes’ debería tener como resultado la eliminación de todos los clientes.