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 |
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.
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.
Ya tenemos la base del diseño de un api ReST, pero aun faltan algunos temas importantes. Continuaremos hablando de ello en el siguiente post.
 |
| Esperando la respuesta a una petición GET |
