REST y Servicios RESTful

Tutor: Ing. Juan E. Talavera Horn

2013

Contenido

Actualizar....

REST. Concepto
Representational State Transfer
Estilo arquitectnico para exponer servicios sobre
HTTP/HTTPS.

Propuesto en tesis doctoral:

Architectural Styles and the Design of Network-basedm
Software Architectures. Roy Fielding. 2000.

Restricciones REST

Cliente-Servidor: El cliente no depende de detalles de

implementacin del componente corriendo en el servidor, y el
servidor no se preocupa por IU, ni mantener el estado
conversacional del cliente.

Stateless: Para reducir acoplamiento y aumentar escalabilidad, el

servidor no mantiene informacin de estado.

Cacheable: Los clientes y proxies pueden cachear respuestas. Los

servicios deben responder indicando si la respuesta es cacheable
y por cuanto tiempo.

Systema en capas: Las peticiones al servidor pasan por servidores

intermediarios que podran implementar balanceo de carga o
cacheo local.

Interfaz uniforme: Interfaz consistente en su diseo, y no

dependiente de aspectos internos del servidor.

Cdigo sobre demanda (opcional): El servidor podra retornar

cdigo ejecutable al cliente: Javascript, Applets, Flash, etc.

Principios REST

Orientados a recursos. Los servicios realizan su trabajo manipulando

recursos identificables de forma nica. (Los sustantivos)

Recursos: Cliente, Producto, Compra, etc.

La URL define un recurso en particular

Las operaciones ejecutables sobre un recurso son: POST, PUT, GET,

DELETE. (Los verbos)

Principios fundamentales:

Todos los recursos son direccionables con una URI

Los recursos se manipulan con los mtodos HTTP estndares

Los mensajes son auto-explicativos (metadatos, versiones, cache,

etc)
Las urls de los servicios son provedas en el cuerpo de los
mensajes de respuestas, permitiendo descubrir dinmicamente
las acciones disponbibles. (Servicios conectados)

Diseo de API REST

Factores a considerar al disear una API
- Mtodo HTTP
- URI del recurso
- Cabeceras y cuerpo de request
- Status code y cuerpo del response

Mtodo HTTP
Mtodo

Operacin CRUD

Seguro

Idempotente

GET

Leer recurso

Si

Si

POST

Crear nuevo recurso.

Servidor asigna URI

No

No

PUT

Actualizar o crear recurso No

cuya URI asigna el
cliente

Si

DELETE

Borrar recurso

Si

No

GET http://{host:port}/library/v1/books/0201709066
PUT http://{host:port}/library/v1/books/0201709066
POST http://{host:port}/library/v1/books/0201709066/reviews
DELETE http://{host:port}/library/v1/books/0201709066

URI del recurso

Deben representar sustantivos, no verbos.
Mal: GET http://{host:port}/library/v1/getBooks
Bien: GET http://{host:port}/library/v1/books

Sustantivos en plural.
Traer todos los libros:
GET http://{host:port}/library/v1/books
Traer un libro:
GET http://{host:port}/library/v1/books/0201709066
Representar modelo jerrquico de datos
GET http://{host:port}/library/v1/books/0201709066/reviews/1

Cabecera y cuerpo del request

POST http://rest.service.com/library/v1/books/0201709066/reviews HTTP/1.1
Content-Type: application/json
Accept: application/json
{"author":"John Doe", "comments":"Very informative."}
Cabeceras usadas:
Content-Type: especifica tipo de dato de payload
Accept: especifica tipo de dato de respuesta esperado
Con XML:
POST http://rest.service.com/library/v1/books/0201709066/reviews HTTP/1.1
Content-Type: application/xml
Accept: application/xml
<resource>
<author>John Doe</author>
<comments>Very informative.</comments>
</resource>

Status code y cuerpo del response

Status codes estndares de HTTP

Rango

Descripcin

1xx (Meta)

Negociaciones con el servidor HTTP

2xx (xito)

Operacin exitosa

3xx (Redireccin)

El cliente debe hacer otra peticin

4xx (Error cliente)

Hay un problema con la peticin del cliente

5xx (Error servidor)

Error interno en el servidor

Status code y cuerpo del response

Ejemplo de respuesta
HTTP/1.1 200 OK
Date: Wed, 5 Sep 2012 06:25:24 GMT
Content-Type: application/json
{"isbn":"1146104553", "author":"Leo Tolstoy", "title":"War and Peace"}

Modelado de recursos
Reflejar relaciones y estructura jerrquica
http://api.nfl.com/v1/divisions/nfc-west/teams/arizona/players
http://api.nfl.com/v1/divisions/nfc-west/teams/arizona
http://api.nfl.com/v1/divisions/nfc-west/teams
http://api.nfl.com/v1/divisions/nfc-west
http://api.nfl.com/v1/divisions

Patrones de recursos

Document
Collection
Store
Controller

Document
Un documento representa un nico recurso (una
entidad)
Ejemplos:
http://rest.service.com/library/v1/books/0201709066
http://rest.service.com/library/v1/books/0201709066/r
eviews/1

Collection
Representa un grupo de documentos
Ejemplo:
http://rest.service.com/library/v1/books/0201709066/reviews

Store
Similar a un collection. Desde el store se pueden obtener
documentos, modificarlos, insertarlos y editarlos.
Diferencias:
El cliente asigna las URIs para los nuevos elementos.
No soporta POST, siempre se crea con PUT.

Controller
No es estrctamente RESTful.
Permite agregar nuevo verbo a un recurso.
Mapear operaciones que no necesariamente se mapean a un
mtodo HTTP.
Siempre deben usar POST.
Ejemplo:
POST http://rest.com/library/v1/books/66/overdue-alerts/1/resend

Crear un servicio REST

@Path("/library")
public class Library
{
//implementation here...
}
Para las peticiones:
GET http://{server}/MyRestService/library/books
GET http://{server}/MyRestService/library/books/1234
POST http://{server}/MyRestService/library/books/1234
DELETE http://{server}/MyRestService/library/books/1234

El mtodo GET
@GET
@Path("/books")
@ProduceMime("application/xml")
public String getBooks()
{
//implementation here...
}
@GET
@Path("/books/{isbn}")
@ProduceMime("application/xml")
public String getBook(@PathParam("isbn")String id)
{
//implementation here...
}

QueryParam
@GET
@Path("/users")
public String getUser(@QueryParam("id")String userId)
{
//implementation here...
}
Para la URL:
/users?id=1234

El mtodo PUT
@PUT
@Path("/books/{isbn}")
@ConsumeMime("application/xml")
public Response addUpdateBook(@PathParam("isbn") String isbn, String body)
{
if (books.containsKey(isbn))
response = Response.status(200).build(); //updated
else
response = Response.status(201).build(); //created
//....
return response;
}

El mtodo DELETE
@DELETE
@Path("/books/{isbn}")
public Response removeBook(@PathParam("isbn")String isbn)
{
//implementation here...
}

Cliente de ejemplo
Obtener un libro:
<form name=datos>
<input type=text name=idlibro onblur=traerDesc()/>
<div id=descLibro></div>
</form>
<script>
function traerDesc() {
Ajax(/library/books/ + $('idlibro').value, GET,
function (var response) {
var libro = jQuery.parseJSON(response);
$('descLibro').innerHTML = libro.descripcion;
}
}
</script>

Cliente de ejemplo
Guardar un libro:
<form name=datos>
<input type=text name=id />
<input type=text name=desc />
<input type=button onclick=guardar() />
</form>
<script>
function guardar() {
Ajax(/library/books/ + $('id').value, PUT,
{ desc :' + $('desc').value + '} ,
function (var response) {
var libro = jQuery.parseJSON(response);
$('descLibro').innerHTML = libro.descripcion;
}
}
</script>

Referencias
RESTful Web Services CookBook. Subbu Allamaraju.
http://www.sourcestream.com/programming-stuff/guide-to-rest-services
http://www.sourcestream.com/programming-stuff/how-to-create-a-restfulweb-service