21/04/2013

Departamento de Lenguajes y
Sistemas Informticos

Implementacin de una API REST

Prctica 8

Arquitectura e Integracin del Software

Curso 2012/2013

ndice

Introduccin
Configuracin del servidor
Ejemplos
Anotaciones
Respuestas
Buenas prcticas
Enlaces

21/04/2013

ndice

Introduccin
Configuracin del servidor
Ejemplos
Anotaciones
Respuestas
Buenas prcticas
Enlaces

Introduccin
En prcticas anteriores hemos estudiado como consumir
servicios REST para integrarlos en nuestras aplicaciones.
Sin embargo, es igualmente importante hacer que nuestras
aplicaciones puedan ser integradas por otros.
El objetivo de la prctica de hoy es aprender a implementar
una API REST en Java haciendo uso del framework RESTEasy,
que implementa la interfaz JAX-RS.

21/04/2013

Introduccin
JAX-RS (JSR-311) es una especificacin Java diseada para
facilitar la implementacin de APIs REST.
Est basada fundamentalmente en el uso de anotaciones (ej.
@GET).
Los desarrolladores decoran las clases Java con las
anotaciones JAX-RS para definir los recursos y las acciones que
pueden ser realizadas sobre stas.
En esta prctica usaremos la implementacin de JAX-RS
proporcionada por RESTEasy.

ndice

Introduccin
Configuracin del servidor
Ejemplos
Anotaciones
Respuestas
Buenas prcticas
Enlaces

21/04/2013

Configuracin del servidor

Pasos a seguir
1. Copiar los JAR a war/WEB-INF/lib

2. Aadir resteasy-jaxrs y jaxrs-api al Build Path

(son los nicos que usaremos directamente en el cdigo).
3. Configurar el web.xml
4. Implementar la clase
javax.ws.rs.core.Application

Configuracin del servidor

Configuracin del Web.xml

21/04/2013

Configuracin del servidor

Implementacin de Application
import javax.ws.rs.core.Application;
public class MusicApplication extends Application {
private Set<Object> singletons = new HashSet<Object>();
private Set<Class<?>> classes = new HashSet<Class<?>>();
// Loads all resources that are implemented in the application so that they can be found by
RESTEasy.
public MusicApplication() {
singletons.add(new PlaylistsResource());
}
public Set<Class<?>> getClasses() {
return classes;
}
public Set<Object> getSingletons() {
return singletons;
}
}

Configuracin del servidor

Implementacin de Application
Las clases aadidas a la lista de singletons se instancian una nica
vez durante la ejecucin. Es decir, no se destruyen entre peticiones.
Las clases aadidas a la lista de classes se instancian por cada
peticin del servicio.
Ms informacin en:
http://docs.jboss.org/resteasy/docs/2.3.1.GA/userguide/html/Insta
llation_Configuration.html#javax.ws.rs.core.Application
OJO! Si integramos la implementacin en un proyecto GWT
aunque la clase Application se ejecuta en servidor, NO debe estar
en el paquete server del proyecto.

21/04/2013

ndice

Introduccin
Configuracin del servidor
Ejemplos
Anotaciones
Respuestas
Buenas prcticas
Enlaces

Ejemplos
GET (Consulta)

21/04/2013

Ejemplos
POST (Insercin)

Ejemplos
PUT (Actualizacin)

21/04/2013

Ejemplos
Cmo puedo probar esto?
Los mtodos GET son fciles de probar desde el navegador.
Para probar los mtodos POST, DELETE y PUT hay varias
opciones:
Usar el cliente REST desarrollado en prcticas anteriores.
Instalar una extensin del navegador que permita hacer las
pruebas:
En Chrome: Advanced REST Client o REST Console
En Firefox: REST Client

ndice

Introduccin
Configuracin del servidor
Ejemplos
Anotaciones
Respuestas
Buenas prcticas
Enlaces

21/04/2013

Anotaciones
@Path indica la URI relativa donde se alojar la clase Java.
Puede aplicarse tanto a clases como a mtodos.
Se pueden definir template URIs haciendo uso de {} (ej.
@Path(/{id})).
@GET, @POST, @PUT, @DELETE indican el verbo HTTP que
procesar el mtodo.
@Produces y @Consumes indican el formato en el que
produce o consume mensajes. Por ejemplo, text/plain o
application/json.

Anotaciones
@PathParam sirve para inyectar como parmetro del mtodo
los valores de la URI template.
Otras anotaciones:

@Context.
@QueryParam.
@CookieParam.
@Form, etc.

Para ms informacin ver secciones 4 7, 9 15 de

http://docs.jboss.org/resteasy/docs/2.3.1.GA/userguide/html
/index.html

21/04/2013

ndice

Introduccin
Configuracin del servidor
Ejemplos
Anotaciones
Respuestas
Buenas prcticas
Enlaces

Respuestas
HTTP tiene un conjunto de respuestas a las peticiones
identificadas con un nmero y una descripcin:

200 OK
201 Created
204 No Content
400 Bad request
404 Not found
409 Conflict
500 Internal Error
Etc.

10

21/04/2013

Respuestas
Respuestas por defecto en RESTEasy
Si el mtodo devuelve un valor, el resultado es 200 OK.
Si el mtodo es void, el resultado es 204 No Content.
Si hay un error al procesar los parmetros de entrada (p.ej. el
JSON de entrada es errneo) el resultado es 400 Bad Request.
Otros errores pueden provocar un 500 Internal Error.

Respuestas
Cmo implemento otras respuestas?
La forma ms sencilla es lanzando excepciones:
@Path("/{listId}")
@GET
@Produces("application/json")
public Playlist getPlaylist(@PathParam("listId") String name ) {
if (playlists.get(name) == null)
throw new NotFoundException("The playlist "+name+" was not found");
return playlists.get(name);
}

Las excepciones predefinidas pueden consultarse en:

http://docs.jboss.org/resteasy/docs/2.3.1.GA/userguide/html
/ExceptionHandling.html#builtinException

11

21/04/2013

Respuestas
Cmo implemento otras respuestas?
Algunas respuestas no tienen excepcin predefinida. En ese caso,
hay que modificar el mtodo para que devuelva Response y
construir la respuesta:

Respuestas
Cmo implemento otras respuestas?
Por ltimo, la respuesta de 201 Created a un mtodo POST es
ms compleja que el resto porque debe:
Indicar cul es la URI del recurso que se ha creado.
Incluir el elemento creado en la respuesta.

12

21/04/2013

ndice

Introduccin
Configuracin del servidor
Ejemplos
Anotaciones
Respuestas
Buenas prcticas
Enlaces

Buenas prcticas
Hay muchas formas de estructurar el cdigo de la aplicacin,
pero siempre es recomendable buscar una que consiga:
Alta cohesin: las clases, mtodos, etc. deben tener pocas
responsabilidades (es decir, no hacer demasiadas cosas).
Bajo acoplamiento: las clases deben depender lo mnimo
posible unas de otras.
Consiguiendo esto lograremos que nuestro cdigo sea ms
fcil de entender y mantener.

13

21/04/2013

Buenas prcticas
Para conseguir una alta cohesin y bajo acoplamiento se
recomienda dividir el cdigo en tres tipos de clases agrupados
en paquetes:
Domain: clases relativas a los conceptos del dominio del
problema (ej. Playlist y Song).
Repositories: clases que representan el concepto de
repositorio o coleccin de objetos de un mismo tipo (ej.
PlaylistRepository)
Resources: clases que representan recursos y tiene las
anotaciones JAX-RS (ej. PlaylistResource y SongResource).

Buenas prcticas
Cada repositorio suele estructurarse en interfaz y una o varias
clases que lo implementan. Un ejemplo bsico de interfaz de
repositorio puede ser:
public interface PlaylistRepository {
public Playlist get(String name);
public void save(Playlist p);
public Collection<Playlist> getAllPlaylists();
public void remove(Playlist p);
}

La interfaz puede tener varias implementaciones. Por ejemplo:

Implementacin que guarda las playlists en un Map
<String,Playlist> en memoria.
Implementacin guarda las playlists en una base de datos.

14

21/04/2013

ndice

Introduccin
Configuracin del servidor
Ejemplos
Anotaciones
Respuestas
Buenas prcticas
Enlaces

Enlaces
RESTEasy
http://www.jboss.org/resteasy/
JAX-RS
http://docs.oracle.com/javaee/6/tutorial/doc/giepu.html

15

21/04/2013

Disclaimer and Terms of Use

All material displayed on this presentation is for teaching and personal use only.

Many of the images that have been used in the presentation are Royalty Free
images taken from http://www.everystockphoto.com/. Other images have been
sourced directly from the Public domain, from where in most cases it is unclear
whether copyright has been explicitly claimed. Our intention is not to infringe
any artists copyright, whether written or visual. We do not claim ownership of
any image that has been freely obtained from the public domain. In the event
that we have freely obtained an image or quotation that has been placed in the
public domain and in doing so have inadvertently used a copyrighted image
without the copyright holders express permission we ask that the copyright
holder writes to us directly, upon which we will contact the copyright holder to
request full written permission to use the quote or images.

16