Servicios Web REST

Un servicio REST (a veces también llamado "servicio web") sirve como protocolo de intercambio de información entre nodos.

Es un "componente" que define un contrato que incluye qué cosas yo puedo pedirle, qué parámetros espera recibir en cada uno de esos "métodos", qué va a retornar, y en qué forma. Bastante genérico, ¿no?

Parecido a un objeto. Peeeero, todo eso dentro del marco web, es decir sobre el protocolo HTTP.

Entonces:

• Enviar un mensaje al servicio va a ser realizar un pedido (GET, POST, PUT, etc)
• Los diferentes servicios se implementan mediante URL's.
• Los parámetros que le puedo pasar tienen que estar representados en Strings (en http lo que viaja es siempre string).
• El resultado que va a devolver el servicio tendrá que ser String también, en algún formato estándar:
  • originalmente ese formato era XML
  • hoy se suele usar JSON

En particular, nosotros vamos a utilizar esta idea, porque nuestro "lado servidor" va a ser un webservice. Y esto nos permite independizar las tecnologías que están de cada lado

• en el server, podemos usar Xtend + XTRest, o bien una aplicación web Grails desde un Tomcat con conversores a JSON, entre otros
• y nuestro cliente podrá ser una aplicación RIA como Angular, o mobile

• Respeta la naturaleza stateless del protocolo http (de la web en general)
  • esto significa que el server no maneja estado de la sesión, sólo almacena en algún medio persistente la información
  • los clientes deben a su vez resolver el manejo del estado, y si son lo suficientemente inteligentes pueden tener su propio almacenamiento (caché) para poder seguir funcionando sin conexión
• Los cuatro métodos en los que podemos enviar un pedido desde un cliente web responden a las cuatro operaciones básicas para un "recurso" (que podemos pensar como un elemento o entidad de nuestro dominio)
  • GET: una consulta
  • PUT: la modificación del estado del recurso
  • POST: genera un nuevo elemento
  • DELETE: la eliminación de dicho recurso
• Los servicios REST trabajan con URLs que funcionan como URIs (Uniform Resource Identifiers) o identificadores de cada uno de los recursos.
  • ¿Qué es un recurso? Cualquier elemento al que se pueda acceder desde un link.
  • En un sistema REST, cada recurso es direccionable únicamente a través de su URI y generalmente las URLs tienen un formato entendible para el usuario final, como veremos a continuación.

Aplicación cliente para probar servicios REST

Para hacer pruebas a diferentes servidores que ofrecen servicios REST te recomendamos que instales alguna de estas aplicaciones

• Para Chrome
  • Advanced REST client: tenés un tutorial básico que explica cómo instalarlo
  • Postman
• Para Firefox
  • RESTClient
  • REST Easy
• Para Safari
  • Paw
  • REST Client

En http://jsonplaceholder.typicode.com/ tenemos varios ejemplos para obtener información de prueba. El primer ejemplo sería recuperar la lista de usuarios de una posible aplicación, eso se consigue de esta manera:

GET /users HTTP/1.1 Host: http://jsonplaceholder.typicode.com

Esto forma la URI http://jsonplaceholder.typicode.com/users, que nos da la siguiente respuesta:

[

  {

    "id": 1,

    "name": "Leanne Graham",

    "username": "Bret",

    "email": "Sincere@april.biz",

    "address": {

      "street": "Kulas Light",

      "suite": "Apt. 556",

      "city": "Gwenborough",

      "zipcode": "92998-3874",

      "geo": {

        "lat": "-37.3159",

        "lng": "81.1496"

      }

    },

    "phone": "1-770-736-8031 x56442",

    "website": "hildegard.org",

    "company": {

      "name": "Romaguera-Crona",

      "catchPhrase": "Multi-layered client-server neural-net",

      "bs": "harness real-time e-markets"

    }

  },

Para ver la representación de una entidad, por ejemplo un usuario, la URI suele incluir un identificador unívoco de ese elemento en el server:

http://jsonplaceholder.typicode.com/users/2

donde

• 2 representaría el identificador del usuario
• y si se trata de una consulta el request se haría mediante un método GET

Para crear un recurso nuevo, debemos pasar su representación JSON o XML al server, utilizando algún framework de la tecnología que utilicemos que nos permita subir el grado de abstracción de nuestros problemas, o bien algún programa que cumpla la funcionalidad de cliente que hace pedidos http, como los clientes que mencionamos en el primer punto o bien curl.

Ejemplo:

curl -X PUT -H 'Content-Type: application/json' -d '{"firstName":"Kris", "lastName":"Jordan"}' servidor.rest.com

Las aplicaciones que respetan estas definiciones se llaman REST-ful.

Más adelante veremos cómo pasar parámetros vía PUT o POST en una herramienta más amigable.

• REST: Paper de la tesis original de Roy Fielding (2000)
• un artículo en castellano sobre REST
• Tutorial de Postman (en inglés, pero pueden ponerle subtítulos o buscar un tutorial en castellano)