API REST
Recursos, representaciones y servicios
En Ejemplo Book tenemos tres recursos raíz: books, authors y editorials. Cada uno representa la colección de libros, autores y editoriales. Los reviews no son recursos raíz, de acuerdo con nuestra decisión de diseño, sino que estos están dentro de un libro.
Los servicios básicos asociados con los recursos raíz tienen la semántica estándar:
Get /books retorna la colección de libros.
Post /books agrega un nuevo libro a la colección.
Put /books no existe.
Get /books/id retorna un libro con identificador id.
Post /books/id no existe.
Put /books/id modifica el libro con identificador id.
Delete /books/id borra el libro con identificador id.
En el diseño de este API los recursos se representan como objetos json. Sin embargo, en cada caso es importante diseñar cuál es la información del recurso que se está enviando (en el caso de Post y Put) o retornando (en el caso de Get).
La decisión general que se tomó y que se explicará detalladamete más adelante para cada recurso es que hay tres representaciones json diferentes por recurso:
- Minimum: Contiene únicamente los atributos propios de la clase.
- Basic: Contiene todo lo de la representación Minimum y las relaciones muchos a uno y uno a uno
- Full: : Contiene todo lo de la representación Basic y las colecciones composite
Get /books retorna la colección de las representaciones Minimun de libros.
Post /books *agrega un nuevo libro a la colección. Recibe la representación Basic*.
Get /books/id retorna la representación Full del libro con identificador id. En este caso, retorna tanto la representación Basic de Editorial como la colección de representaciones Full de reviews.
Put /books/id modifica el libro con identificador id. Recibe la representación Basic.
Decisiones de implementación
La siguiente figura muestra la estructura de archivos de la implementación del api rest de Ejemplo Book. Por simplicidad, estas fuentes está en el proyecto bookstore.web.
Figura 1.
En la figura 1, la carpeta resources contiene una clase por cada recurso principal de la aplicación y la clase RestConfig.java que define la raíz de la url para acceder a los servicios.
La figura 2 muestra el diagrama de clases correspondiente a la implementación del recurso Book del api rest.
Figura 2.
Cada clase recurso contiene los métodos anotados para responder a los llamados http. Para realizar su función cada método invoca a la lógica del backend de la aplicación a través de la interfaz IBookLogic cuya implementación es inyectada dentro de la clase recurso.
La lógica de la aplicación está implementada utilizando clases Entity de JEE7, sin embargo, el api rest debe retornar a los clientes objetos json. Para que esto sea posible, cada clase recurso tiene una utilidad Converter que convierte Entity a su correspondiente DTO y también covierte DTO a Entities. Una vez en DTO, Jax-rs utilizando Jaxb, convierte el objeto al formato Json. La clase utilidad converter tiene métodos para manipular las distintas representaciones del recurso.
La figura 3 muestra el diagrama de secuencia del llamado a GET api/books
Figura 3.