Implementación servicios REST

Los conceptos básicos de REST se encuentran aquí

Diseño del API REST del MarketPlace

El proceso de diseño del API REST consistió en:

Identificar las entidades conceptuales que se quieren exhibir como servicios
Crear una URL para cada recurso (en plural).
Categorizar los recursos de acuerdo con:
El cliente recibirá una representación del recurso (HTTP GET). Todos los recursos que se accedan vía HTTP GET no deben tener efecto de borde (solo trae una representación del recurso)
El cliente modificará o creará el recurso (HTTP POST, PUT, y/o DELETE).
1. Sobre una colección se puede traer todos los elementos de la colección, traer un elemento particular, agregar un elemento particular, Borrar un elemento.
2. Los elementos en las colecciones deben tener una representación en JSON.

Para la documentación del API del marketplace ver el Read.me

Vista general del servicio

Cuando se realiza una petición al API REST, los datos enviados pasan por diferentes formatos de representación con el fin facilitar la operación con los mismos. Los formatos por los que pasa son:

JSON: Representación de los datos usado en JavaScript
DTO: Data Transfer Object. Son POJOs que permiten su serialización y deserialización con JAX-B
Entity: POJOs anotado con @Entity.

![Api Representation][api_rep]

JSON

JSON es la notación usada en JavaScript para representar objetos. Consiste en encerrar entre llaves el objeto, donde cada atributo puede definirse como llave/valor.

{
  name: 'Alice in wonderland',
  price: 30000,
  editorial: {
    name: 'Norma'
  }
}

Inicialmente, el frontend envía los datos en este formato (convertiro a String) al backend. Dado que JSON ya es un estandar para, la mayoría de implementaciones en backend lo soportan.

DTO

Los DTO (Data Transfer Object) son POJO anotados con @XmlRootElement de JAX-B, lo cual permite su serialización y deserialización automática.

Cuando el servicio REST recibe una petición HTTP con un objeto JSON, automáticamente JAX-B deserializa el JSON recibido y lo convierte en un objeto Java (en este caso llamados DTO). De esta manera se puede manipular fácilmente la información recibida a través de sus accesores (getters/setters).

Entity

La capa de lógica realiza sus operaciones usando entidades de JPA. Estas son POJO anotados con @Entity, lo cual permite a JPA realizar el mapeo con base de datos.

Para proveer a la capa lógica las entidades que requiere, es necesario convertir los datos de los DTO a entidades. Para esto se crean clases Converter que realizan conversiones bidireccionales entre estos. De esta manera, la comunicación con la capa de lógica se mantiene, sin dejar a un lado la separación entre la representación de los servicios y de las entidades de base de datos.

Implementación servicios RESTful en Java

Para esta implementación utilizamos el API JAX-RS, que ayuda a escribir aplicaciones RESTful tanto en el cliente como en el lado servidor.

JAX-RS usa anotaciones para facilitar el desarrollo y está integrado con Java EE desde la vesión 6.

Recursos raíz

Un recurso raíz es un punto de entrada a los recursos del API. Para crearlos con JAX-RS es necesario anotar la clase con @PATH. Esta anotación recibe un parámetro que indica la ruta donde el recursos está localizado. El siguiente es una parte del archivo BookService.java.

package co.edu.uniandes.csw.bookstore.services;

...
import javax.ws.rs.Path;
...

@Path("books")
...
public class BookResource {

}

Métodos sobre los Recursos

Son métodos java que están ligados a solicitudes HTTP. La asociación se hace a través de las anotaciones @GET, @PUT, …

@GET
public List<BookDTO> getBooks() {
    // Devuelve un listado de Book
}

@POST
public BookDTO createBook(BookDTO dto) {
    // Crea un Book en base de datos
}

@Consumes y @Produces

Son anotaciones que indican la representación de los recursos manipulados en los llamados. En nuestro ejemplo, esta representación es en formato JSON.

@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
public class BookResource {
    ...
}

[api_rep]: https://cacoo.com/diagrams/vs92qtN3Veql7Ah6-A01BB.png "Data Representation"

@RequestScoped

Se usa la anotación @RequestScoped para garantizar que a partir de este punto se inicia una transacción. Es decir, que se realice completamente o se haga rollback si se ha detectado algún error. Por ejemplo, al momento de una conversión de un DTO a Entity si se ha detectado un error de formato esta anotación previene que se almacenen datos erroneos en la Base de Datos porque deshace la transacción.

@Consumes(MediaType.APPLICATION_JSON)
@Produces(MediaType.APPLICATION_JSON)
@RequestScoped
public class BookResource {
    ...
}

Implementación Servicios RESTful en Java