REST y Servicios RESTfulTutor: Ing. Juan E. Talavera Horn

2013

ContenidoActualizar....

REST. ConceptoRepresentational State Transfer

Estilo arquitectnico para exponer servicios sobreHTTP/HTTPS.

Propuesto en tesis doctoral:Architectural Styles and the Design of Network-basedm Software Architectures. Roy Fielding. 2000.

Restricciones RESTCliente-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 RESTOrientados 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 particularLas operaciones ejecutables sobre un recurso son: POST, PUT, GET, DELETE. (Los verbos)Principios fundamentales:Todos los recursos son direccionables con una URILos recursos se manipulan con los mtodos HTTP estndaresLos 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 RESTFactores a considerar al disear una API

Mtodo HTTPURI del recursoCabeceras y cuerpo de requestStatus code y cuerpo del response

Mtodo HTTPGET 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

MtodoOperacin CRUDSeguroIdempotenteGETLeer recursoSiSiPOSTCrear nuevo recurso. Servidor asigna URINoNoPUTActualizar o crear recurso cuya URI asigna el clienteNoSiDELETEBorrar recursoNoSi

URI del recursoDeben representar sustantivos, no verbos.

Mal: GET http://{host:port}/library/v1/getBooksBien: 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 requestPOST http://rest.service.com/library/v1/books/0201709066/reviews HTTP/1.1Content-Type: application/jsonAccept: application/json{"author":"John Doe", "comments":"Very informative."}

Cabeceras usadas:Content-Type: especifica tipo de dato de payloadAccept: especifica tipo de dato de respuesta esperado

Con XML:

POST http://rest.service.com/library/v1/books/0201709066/reviews HTTP/1.1Content-Type: application/xmlAccept: application/xml

John Doe Very informative.

Status code y cuerpo del responseStatus codes estndares de HTTP

RangoDescripcin1xx (Meta)Negociaciones con el servidor HTTP2xx (xito)Operacin exitosa3xx (Redireccin)El cliente debe hacer otra peticin 4xx (Error cliente)Hay un problema con la peticin del cliente5xx (Error servidor)Error interno en el servidor

Status code y cuerpo del responseEjemplo de respuesta

HTTP/1.1 200 OKDate: Wed, 5 Sep 2012 06:25:24 GMTContent-Type: application/json{"isbn":"1146104553", "author":"Leo Tolstoy", "title":"War and Peace"}

Modelado de recursosReflejar relaciones y estructura jerrquica

http://api.nfl.com/v1/divisions/nfc-west/teams/arizona/playershttp://api.nfl.com/v1/divisions/nfc-west/teams/arizonahttp://api.nfl.com/v1/divisions/nfc-west/teamshttp://api.nfl.com/v1/divisions/nfc-westhttp://api.nfl.com/v1/divisions

Patrones de recursosDocumentCollectionStoreController

DocumentUn documento representa un nico recurso (una entidad)

Ejemplos:

http://rest.service.com/library/v1/books/0201709066http://rest.service.com/library/v1/books/0201709066/reviews/1

CollectionRepresenta un grupo de documentos

Ejemplo:

http://rest.service.com/library/v1/books/0201709066/reviews

StoreSimilar a un collection. Desde el store se pueden obtenerdocumentos, modificarlos, insertarlos y editarlos.

Diferencias:

El cliente asigna las URIs para los nuevos elementos.

No soporta POST, siempre se crea con PUT.

ControllerNo 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/booksGET http://{server}/MyRestService/library/books/1234POST http://{server}/MyRestService/library/books/1234DELETE 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(); //updatedelseresponse = 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 ejemploObtener un libro:

function traerDesc() {Ajax(/library/books/ + $('idlibro').value, GET,function (var response) {var libro = jQuery.parseJSON(response);$('descLibro').innerHTML = libro.descripcion;} }

Cliente de ejemploGuardar un libro:

function guardar() {Ajax(/library/books/ + $('id').value, PUT,{ desc :' + $('desc').value + '} ,function (var response) {var libro = jQuery.parseJSON(response);$('descLibro').innerHTML = libro.descripcion;} }

ReferenciasRESTful 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-restful-web-service