Ya hemos estado viendo lo básico del
Core de Spring, también hemos estado viendo lo básico de
JPA/ORM para dar persistencia a los datos. Ahora
vamos a ver la capa de presentación mostrando nuestros datos por una API REST.
REST se clasifica en varios niveles en función de su madurez. En general basta con un
servicio web que atienda peticiones por protocolo HTTP y devuelva datos serializados (normalmente en JSON, pero puede ser otro formato también):
Nivel 0. Estos dos puntos parecen antagónicos con
SOAP que permite cualquier protocolo para el transporte, pero los datos deben intercambiarse por XML con un esquema rígido.
URLs bien definidas identificando recursos: colecciones, elementos individuales y otras "operaciones":
Nivel 1.
Para las peticiones se
usarán verbos HTTP para operaciones CRUD (
GET,
POST,
PUT,
DELETE,...):
Nivel 2.
El nivel más alto se logra consiguiendo HATEOAS/Hipermedia. Esto significa que, desde la raíz de nuestro servicio REST, todas las llamadas que se puedan realizar deben ser autodescubribles por medio de enlaces URL que representan las asociaciones de los distintos recursos:
Nivel 3. Un ejemplo sería la
API con datos sobre Star Wars donde se ven los enlaces de Luke con su planeta natal, peliculas donde sale, sus vehículos, raza, etc... siendo todos ellos urls al recurso (pero no incrustando sus datos).
Otra característica es que
REST no mantiene estado. Cada petición y respuesta debe contener toda la información necesaria.
Después de esta introducción, recomiendo ver un video que habla de todo ello de una forma muy práctica y directa llamado
"Horneando APIs" de Paradigma Digital. y que para mí es como un resumen en español del libro
REST API Design Rulebook. Nosotros vamos a poner en práctica todo esto con:
- Spring Data Rest: que es una de las dependencias que usamos cuando generamos el proyecto
inicialmente con Spring Initialzr. Si miramos nuestro
build.gradle se
identifica perfectamente la dependencia
- y nuestro ejemplo de Datos Deportivos
Empezamos este tutorial dando persistencia a
Participantes y a
Partidos que tenía una colección de
Sucesos. Cargamos los datos de 237 participantes usando su DAO correpondiente y también cargamos unos partidos aleatorios con sucesos (en general sin decir si son goles, tarjetas, etc...). Esta forma de trabajar no permite la interacción que se espera de una arquitectura cliente-servidor.
Al final de esta entrada tendremos una colección para Postman que nos permitirá interaccionar con nuestra aplicación mediante llamadas HTTP y nos permitirá hacer pruebas más fácil. Por tanto el punto inicial es este
commit de nuestro repositorio.
Si en este punto no cerramos la aplicación con nuestra última linea del
main veríamos que ya se están exponiendo los repositorios. Hacemos una llamada a
http://localhost:8080/ y tendremos la siguiente respuesta:
{
"_links": {
"partidoConIds": {
"href": "http://localhost:8080/partidoConIds{?page,size,sort}",
"templated": true
},
"participantes": {
"href": "http://localhost:8080/participantes{?page,size,sort}",
"templated": true
},
"sucesoConIds": {
"href": "http://localhost:8080/sucesoConIds{?page,size,sort}",
"templated": true
},
"profile": {
"href": "http://localhost:8080/profile"
}
}
}
Es decir,
por defecto, todos los repositorios serán mostrados por Spring Data Rest si no se configura lo contrario. Voy añadir dos
propiedades para configurar dos aspectos: que sólo se muestre lo anotado con
@(Repository)RestResource y el
prefijo de la API:
spring.data.rest.detection-strategy=annotated
spring.data.rest.basePath=/api
Esto lo pondré en un archivo llamada
rest.properties que
añadiré con @PropertySource como vimos anteriormente mediante una clase de configuración llamada
ConfiguracionJava que luego usaré para más cosas:
@Configuration
@PropertySource({ "classpath:config/rest.properties" })
public class ConfiguracionPorJava {}
Y la añadimos a nuestra aplicación:
@Import(ConfiguracionPorJava.class)
public class DatosdeportivosapiApplication {...}
Ahora ya no se mostrará lo anterior, así que lo siguiente será modificar nuestras anotaciones
@Repository por
@RepositoryRestResource que es de Spring Data Rest.
@RepositoryRestResource admite varios valores para configurar nuestro repositorio. Pongo el ejemplo para
SucesoConId:
@RepositoryRestResource(path="sucesos",
// exported=false,
itemResourceRel="suceso",
collectionResourceRel="sucesos")
public interface SucesoDAO extends JpaRepository<SucesoConId, Long> {
}
Aquí se puede ver que podemos decidir el path para este recurso y los nombres que tendrán las relaciones tanto para colección como para elemento (al final de la entrada se ve qué es esto de las relaciones).
Recomiendo usar al menos esta configuración porque de lo contrario generará esos nombres automáticamente y puede que el resultado no nos guste (ver cómo se veía antes más arriba).
He comentado el valor
exported=false ya que evita que se exponga el recurso. Este valor habría que usarlo si no quisiéramos mostrar este recurso. Por defecto tiene valor
true.
Con esto
termina el Paso 1, pero los recursos de
Partidos y
Sucesos no se pueden visitar ya que Jackson no es capaz de serializarlos correctamente porque no son simples POJOs. Vamos a
customizar cómo debe serializarse aplicando propiedades para jackson, implementando unos MixIn y añadiéndolos a nuestro
ObjectMapper. Como la entrada no va de esto y para no alargarla, lo mejor es ver este segundo paso en vivo en el webinar, pero aquí
nos vamos a colocar en el commit del Paso 2 para continuar y terminar con nuestra API RESTful HATEOAS.
El resultado hasta aquí muestra una API con un array de
Sucesos en cada
Partido y sin mostrar el
partido al que corresponde cada
Suceso para no entrar en bucle. También vemos links de paginación dando cierta navegabilidad, pero no se puede navegar entre
Partidos y
Sucesos correctamente.
Para implementar HATEOAS correctamente Spring necesita la siguiente información sobre las relaciones:
- Anotar con
@OneToMany y @ManyToOne los miembros necesarios. No sirve sólo con que tenga la información JPA.
- Los recursos para asociar deben tener repositorio propio (esto ya está hecho)
- Se debe conocer la implementación concreta si la relación hace referencia a un tipo abstracto (debe saber qué
Suceso debe deserializarse: deserialización polimórfica)
Para el primer punto no hace falta anotar las clases con
@Entity ni
@Id. Con
anotar el miembro correspondiente es suficiente. Como no se tiene acceso al campo sucesos lo que hacemos es sobre escribirlo y anotarlo
incluyendo la entidad objetivo (punto 3):
@Override
@OneToMany(targetEntity=SucesoConId.class)
public Collection<Suceso> getSucesos() {
return super.getSucesos();
}
Para el caso de
SucesoConId basta con anotar el campo con
@ManyToOne.
@ManyToOne
PartidoConId partido;
Comparto también una
colección, para probar la
API en el punto actual.
