Implementación de una API RESTful con Spring Framework (I): Introducción

Estreno blog con una serie de entradas en las que veremos cómo implementar una API RESTful sobre plataforma Java utilizando diversos módulos del siempre maravilloso Spring. Concretamente, utilizaremos el módulo principal Spring Framework y el módulo Spring Data. De este último, usaremos las funcionalidades para acceso a datos mediante JPA (Java Persistence API), utilizando Hibernate como proveedor JPA.

Para ponernos en situación, vamos a suponer que queremos implementar una API que nos permita gestionar todos los libros que tenemos en nuestra biblioteca personal. En esta primera entrada veremos cómo definir algunos servicios básicos de tipo CRUD (Create Read Update Delete) para una gestión inicial de los libros.

Las herramientas necesarias para seguir esta serie de entradas son las siguientes:

• Eclipse
• Maven
• Java JDK 8 
• Git
• Advanced REST Client

Concretamente, en esta entrada trataremos los siguientes puntos de cara a la implementación del servicio, que iremos completando en siguientes entradas.

• Definición de los servicios
• Definición de la base de datos
• Estructura del proyecto
• Despliegue del servicio
• Conclusiones

Definición de los servicios

Empezaremos definiendo los servicios REST para una gestión básica de los libros. Para ello, contaremos con los siguientes servicios:

• GET /libros: obtener una lista de todos los libros de la biblioteca.
• GET /libros/1: obtener un libro concreto por su identificador.
• POST /libros: crear un nuevo libro.
• PUT /libros/1: actualizar un libro concreto por su identificador.
• DELETE /libros/1: borrar un libro concreto por su identificador.

Es recomendable que los nombres (nunca verbos) que utilicemos para identificar los servicios estén en su forma plural en base al recurso gestionado, tal y como hemos especificado con nuestros libros. Existen multitud de buenas prácticas para la implementación de servicios REST. En este y este enlace podréis encontrar multitud de buenos consejos.

Definición de la base de datos

A continuación, definiremos la base de datos para almacenar los libros. Inicialmente, contaremos con un identificador, el nombre y el año de publicación de cada libro. El siguiente esquema, corresponde a la creación de la tabla para almacenar las propiedades mencionadas de cada libro. Este esquema se basa en la sintaxis de la base de datos HSQLDB, la cual usaremos en su modo embebido para este ejemplo.

En la línea 2 podemos observar la creación de la clave primaria mediante la instrucción IDENTITY, la cual creará una clave auto-incremental en base de datos de forma automática.
Además, hemos creado un script para insertar nuestros primeros libros de forma automática cuando el servicio se despliegue.

Estructura del proyecto

El proyecto está soportado por Maven. En el enlace que se encuentra al final del post encontrarás el acceso a mi repositorio Github para que puedas descargar el código del proyecto y empieces a trastear con él. La estructura del proyecto es la que se muestra a continuación.

En esta estructura, podemos encontrar diferentes paquetes con clases Java.

• bean: paquete donde se encuentran las entidades Java que representan los recursos, en este caso libros.
• controller: aquí se encuentran los controladores que se encargarán de procesar las peticiones que lleguen para gestionar los libros (GET, POST, PUT y DELETE)
• facade: en este paquete se encuentran las clases donde se implementa la lógica de negocio, siguiendo el patrón facade. 
• repository: aquí se encuentran las clases que implementarán el acceso a la base de datos.

Además, encontramos los esquemas de creación de la base de datos e inserción de datos en la carpeta db. También tenemos los ficheros de configuración de Spring (applicationContext.xml y dispacherServlet.xml) en la carpeta del mismo nombre, así como el fichero de Maven pom.xml con las dependencias y plugins necesarios para el despliegue del servicio.

Despliegue del servicio 

El servicio implementado se despliega en un servidor Tomcat que ya se incluye embebido en el proyecto. Para ello, hay que ejecutar el comando Maven siguiente: clean tomcat7:run
Esto iniciará el servicio, creando de forma automática la base de datos e insertando los datos que se encuentran en el script db/insert.sql. Verás que también se abre una ventana con el manager de gestión de datos para la base de datos embebida HSQL. Desde aquí podremos consultar y realizar modificaciones de nuestros datos directamente.

Para interactuar con el servicio, podemos acceder a la URL http://localhost:8080/spring.rest.jpa.i/libros mediante el cliente Advanced Rest Client o mediante un navegador web. Esta petición nos devolverá un listado de libros en formato JSON.

Conclusiones

En siguientes entradas explicaré cómo hemos implementado las diferentes clases (beans, controllers, etc.) y la configuración de Spring, además de completar esta API con nuevos servicios, más entidades, nuevas relaciones entre entidades, etc. También, veremos otros temas relacionados con el diseño de la API, como el versionado, la seguridad, cacheo, serialización avanzada, etc. De esta forma iremos tratando diferentes configuraciones y funcionalidades que nos ofrece Spring Data JPA para hacernos la vida más fácil y placentera.

Pulsa aquí para acceder al código de esta entrada en mi repositorio Github