rest

¿Qué es rest?


REpresentational State Transfer

  • El término se originó en el año 2000 en la tesis doctoral Architectural Styles and the Design of Network-based Software Architectures escrita por Roy Fielding, uno de los principales autores de la especificación del protocolo HTTP.

  • REST se refiere a un estilo de arquitectura para sistemas hipermedia distribuidos constituido por un conjunto de principios y restricciones.

Principios de arquitectura


  • Performance
  • Scalability
  • Simplicity
  • Modifiability
  • Visibility 
  • Portability
  • Reliability

Restricciones de arquitectura


  • Client-Server:  separación de responsabilidades: clientes (user-interface y user-state) y servidores (data-storage).
    +simplicity +portability +scalability

  • Stateless: comunicaciones entre cliente y servidor sin estado. 
    +visibility +reliability +scalability

  • Cache: las respuestas del servidor deben indicar si son o no cacheables.
    +efficiency +scalability +user-perceived performance

restricciones de arquitectura


  • Layered System:  sistemas conformados por varias capas o intermerdiarios (proxies, gateways, firewalls).
    +simplicity +scalability
  • Uniform Interface: interfaz uniforme entre cliente y servidor.
    • Identificación de recursos
    • Manipulación de recursos a través de representaciones
    • Mensajes autodescriptivos
    • Hypermedia as the Engine of Application State.
       +simplicity +visibility +independent evolvability

ELEMENTOS DE ARQUITECTURA


  • Resource: principal abstracción de la información en REST.

  • Resource Identifier: clave utilizada para identificar inequívocamente a un recurso (URI).

  • Representation: el estado actual o solicitado de un recurso utilizado para ser transferido entre los distintos componentes.

  • Representation metadata: información que describe el formato de dato de la representación  (media type).

ROA


Resource-Oriented Architecture

Los elementos serán modelados como recursos, los cuales serán referenciados con un identificador global.


Para manipular estos recursos, los distintos componentes de la red (clientes y servidores) se comunicarán a través de una interfaz uniforme y el intercambio de representaciones de estos recursos.



REST
over

HTTP

Richardson's maturity model


Modelo que organiza los principales elementos REST en cuatro niveles.








Level o: The Swamp of pox

http

El protocolo HTTP es utilizado como el medio de comunicación:

http://api.zonajobs.com/createUser

http://api.zonajobs.com/retrieveUser?userId=123

http://api.zonajobs.com/updateUser?userId=123
http://api.zonajobs.com/deleteUser?userId=123

http://api.zonajobs.com/retrieveUsers





LEVEL 1: RESOURCES

RECURSOS

El diseño de la interfaz debe ser orientado a recursos: 


http://api.zonajobs.com/users/create?userId=235

http://api.zonajobs.com/users/retrieve?userId=235

http://api.zonajobs.com/users/update?userId=235

http://api.zonajobs.com/users/delete?userId=235

http://api.zonajobs.com/users/retrieveAll





Level 2. HTTP Verbs

http methods

Las acciones deben estar definidas en los métodos HTTP.

POST GET PUT DELETE
Crea  una nueva entidad en la colección. El identificador de la nueva entidad es asignado automaticamente. 
Puede ser utilizado también para realizar actualizaciones parciales (es el único método no idempotente) 		Devuelve una representación del elemento especificado expresada en algún Internet Media Type apropiado.
 Reemplaza el elemento espcificado o si no existe lo crea. No soporta actualizaciones parciales (es idempotente).
 Elimina el elemento especificado.

HTTP METHODS

Los métodos se corresponden generalmente con las operaciones CRUD.


http://api.zonajobs.com/users      [POST]     Create

http://api.zonajobs.com/users/34   [GET]      Retrieve

http://api.zonajobs.com/users/34   [PUT]      Update

http://api.zonajobs.com/users/34   [DELETE]   Delete

http://api.zonajobs.com/users      [GET]      Retrieve

HTTP STATUS CODES

Los responses deben contener el código de estado correcto para cada caso:

  • 1xx informational

  • 2XX SUCCESS

  • 3xx Redirection

  • 4xx Client Error

  • 5xx Server Error

2xx success

Esta clase de código de estado indica que el request fue recibido correctamente, entendido y aceptado.

  • 200 OK
  • 201 Created
  • 202 Accepted
  • 204 No Content

4XX client error

Esta clase de código de estado indica que hubo un error en el request por parte del cliente.

  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not found
  • 405 Metho Not Allowed

5XX CLIENT ERROR

Esta clase de código de estado indica que el servidor ha encontrado un error o no puede resolver el request.

  • 500 Internal Server Error
  • 501 Not Implemented
  • 503 Service Unavailable






Level 3: Hypermedia controls

INTERNET MEDIA TYPES

  • Inidican el tipo de dato contenido en el body del request y el response.

  • Se encuentran definidos en el HEADER :
    • Request: Accept 
    • Response: Content-type
         
  • Ejemplos:
    • application/json
    • application/xml
    • text/plain
    • image/jpg

HATEOAS

Hypermedia As The Engine Of Application State

Este principio sostiene que un cliente debe interactuar con una aplicación enteramente a través de referencias hypermedia provistas dinámicamente por el servidor.

Un cliente dentro de un contexto REST no debe tener nigún conocimiento previo de la API más alla de un punto de entrada y un entendimiento general del funcionamiento de un sistema hypermedia.

ejemplo

GET http://api.zonajobs.com.ar/users/lregnier@dridco.com
{
  "href": "http://api.zonajobs.com.ar/users/lregnier@dridco.com",  "username": "lregnier",
  "email": "lregnier@dridco.com",
  "name": {
    "firstNames": "Santiago",
    "lastNames": "pichon"
  },
  "baseData": {    "href": "http://api.zonajobs.com.ar/users/lregnier@dridco.com/baseData"  },
  "curriculums": [     {     "href": "http://api.zonajobs.com.ar/users/lregnier@dridco.com/curriulums/1642","href": "http://api.zonajobs.com.ar/users/lregnier@dridco.com/curriulums/6876"
    }
   ]
  }}

glory of rest


100% REST compliant
=
RESTFUL




ejemplos




get




post




put




delete




BUENAS PRÁCTICAS

HREF

Usados en lugar de IDs:
[GET] http://api.zonajobs.com/users/31_test@zonajobs.com 
{    
    "href": "http://api.zonajobs.com/users/31_test@zonajobs.com",
    "zonaJobsId": {
        "country": "PA",
        "id": 31
    },
    "username": "arguelles",
    "email": "31_test@zonajobs.com",
    "name": {
       "href": "http://api.zonajobs.com/users/31_test@zonajobs.com/name"        
    },
    "baseData": {
       "href": "http://api.zonajobs.com/users/31_test@zonajobs.com/base-data"
    }
}

Reference (link) expansion

 [GET] http://api.zonajobs.com/users/31_test@zonajobs.com?expand=name
{ "href": "http://api.zonajobs.com/users/31_test@zonajobs.com",
    "zonaJobsId": {
        "country": "PA",
        "id": 31
    },
    "username": "arguelles",
    "email": "31_test@zonajobs.com",
    "name": {
        "href": "http://api.zonajobs.com/users/31_test@zonajobs.com/name",
        "firstNames": "Luis Daniel",
        "lastNames": "Arguelles"
    },    "baseData": {
       "href": "http://api.zonajobs.com/users/31_test@zonajobs.com/base-data"
    }
}

Partial representations


[GET] http://api.zonajobs.com/users/31_test@zonajobs.com?fields=username,email
{    "href": "http://api.zonajobs.com/users/31_test@zonajobs.com",
    "username": "arguelles",
    "email": "31_test@zonajobs.com"
}

pagination

[GET] http://api.zonajobs.com/users?offset=50&limit=25
{
  "href": "http://api.zonajobs.com/users",
  "offset": 50,
  "limit": 25,
  "first": { 
    "href": "http://api.zonajobs.com/users?offset=0"
  },
  "prev": {
    "href": "http://api.zonajobs.com/users?offset=25"
  },
  "items": [
    {"href": "http://api.zonajobs.com/users/juan@dridco.com"},
    {"href": "http://api.zonajobs.com/users/pablo@dridco.com"},
    {"href": "..."},
    {"href": "..."},    ...
  ]
}

error handling

[POST] http://api.zonajobs.com/users
400 Bad Request
{
  "status": 400,

  "code": 40024, // because HTTP has too few codes
    // Ready-to-use user-friendly message:  "message": "Missing mandatory field [username].",
  // Dev-friendly message, can be stacktrace etc.
  "developerMessage": "Field [username] is mandatory when
   creating a new user. White spaces and special characters are not allowed.",

  "moreInfo": "http://api.zonajobs.com/errors/40024"
}

conclusiones

REST define una serie de restricciones de arquitectura que al ser aplicadas nos brindan: 

  • Escalabilidad
  • Interfaces simples que cubren múltiples casos
  • Desarrollo independiente de componentes: clientes y servidores (frontend y backend)
  • Encapsulamiento de sistemas legacy
  • Refuerzo de seguridad (HTTPS)
  • Tolerancia a fallos

¿Ejemplo de sistema REst?


World Wide Web

WWW representa la mayor implementación de un sistema conforme a una arquitectura de estilo REST.

otros


  • Autenticación: BASIC, OAuth, HMAC

  • Rest en JAVA (JAX-RS): RestEasy, Jersey

  • Rest en SCALA: Spray

Links



REST

By Leonardo Regnier

Made with Slides.com

REST

  • 1,323

More from Leonardo Regnier