Api Rest

En esta entra voy a explicar los que es un api Rest

¿Qué es REST?
REpresentational State Transfer, es una arquitectura de tipo SOA que esta basado en HTTP.

REST nos permite crear servicios que pueden ser comsumidos por cualquier dispositivo, cliente o otro servicio REST que conozca el protocolo HTTP,
como consecuencia esto los servios rest son mas simples que otras alternativas que se han usado en los últimos años como SOAP y XML-RPC.

REST se definió en el 2000 por Roy Fielding, coautor principal también de la especificación HTTP.

Existen tres niveles de calidad a la hora de aplicar REST en el desarrollo de una API
Estos niveles son:

•     Uso correcto de URIs
•     Uso correcto de HTTP.
•     Implementar Hypermedia.

   
Una de las caracteriscas de Rest es un servicio sin estado es decir toda la información que se necesaria para mostrar la
información que se solicita debe estar en la consulta por parte del cliente.

Nivel 1: Uso correcto de URIs

Denominamos recurso el acceso a la información del servicio rest.

Las URL, Uniform Resource Locator , son un tipo de URI, Uniform Resource Identifier, que nos permite de identificar de forma única el recurso,
nos permite localizarlo para poder acceder a él o compartir su ubicación.

Estructura de una URL:

{protocolo}://{dominio o hostname}[:puerto (opcional)]/{ruta del recurso}?{consulta}

Como siempre hay unas reglas para el nombrado de los recursos de nuestras Apis Rest:

•     Los nombres de URI no deben implicar una acción, por lo tanto debe evitarse usar verbos en ellos.
•     Deben ser únicas, no debemos tener más de una URI para identificar un mismo recurso.
•     Deben ser independiente de formato.
•     Deben mantener una jerarquía lógica.
•     Los filtrados de información de un recurso no se hacen en la URI.

Nivel 2: HTTP

Para desarrollar APIs REST se debe dominar y conocer los siguientes aspectos:

•     Métodos HTTP
•     Códigos de estado
•     Aceptación de tipos de contenido  

Métodos.

Como hemos nombrado anteriormente, en la url's no debemos poner la accion porque HTTP nos proporciona los siguientes métodos con los cuales debemos operar:

•     GET:  consultar recursos
•     POST:  crear recursos
•     PUT:  editar recursos
•     DELETE:  eliminar recursos.
•     PATCH: editar partes concretas de un recurso.   

Códigos de estado.

Uno de los errores más frecuentes a la hora de construir una API suele ser el desarrollo
de APIs con códigos de error propios.

Ejemplo

Petición
========
PUT /coches/123

Respuesta
=========
Status Code 200
Content:
{
  success: false,
  code:    734,
  error:   "datos insuficientes"
}

Como podemos ver en el ejemplo se devuelve un código de estado 200, que significa que la petición se ha realizado correctamente,
pero, estamos devolviendo en el cuerpo de la respuesta un error y no el recurso solicitado en la URL.

HTTP tiene un gran abanico muy amplio que cubre todas las posibles indicaciones que vamos a tener que añadir en nuestras respuestas cuando las operaciones han ido bien o mal.

Petición
========
PUT /caches/123

Respuesta
=========
Status Code 400
Content:
{
  message: "se debe especificar un id de coche"
}

Tipos y formatos de contenido.

Cuando hablamos sobre URLs, vimos también que no era correcto indicar el tipo de formato de un recurso al cual queremos acceder o manipular.

HTTP nos permite especificar en qué formato queremos recibir el recurso, pudiendo indicar varios en orden de preferencia, para ello utilizamos el header Accept.

Nuestra API devolverá el recurso en el primer formato disponible y, de no poder mostrar el recurso en ninguno de los formatos indicados por el cliente mediante el header Accept, devolverá el código de estado HTTP 406.

Nivel 3: Hypermedia.

Con Hypermedia básicamente añadimos información extra al recurso sobre su conexión a otros recursos relacionados con él.

Aquí tenemos un ejemplo:    

<pedido>
     <id>666</id>
     <estado>Procesado</estado>

     <links>

       <link rel="factura">

        http://example.com/api/pedido/666/factura 

           </link> 

    </links>   

 </pedido>

En este ejemplo vemos cómo indicar en un xml que representa un pedido, el enlace al recurso de la factura relacionada con el mismo.

Sin embargo, necesitamos que el cliente que accede a nuestra API entienda que esa información no es propia del recurso, sino que es información añadida que puede utilizar para enlazar el pedido con la factura.

Para ello conseguir esto, debemos utilizar las cabeceras Accept y Content-Type, para que tanto el cliente como la API, sepan que están hablando hypermedia.

Por ejemplo:

Petición
========
GET /pedido/666
Accept: application/nuestra_api+xml, text/xml

Respuesta
=========
Status Code: 200
Content-Type: application/nuestra_api+xml
Content:

<pedido>
 <id>666</id>
 <estado>Procesado</estado>
 <links>
   <link rel="factura">

http://example.com/api/pedido/666/factura

   </link>
 </links>
</pedido>

Como vemos, el cliente solicita el formato application/nuestra_api+xml de forma preferente al formato text/xml.
De esta forma, le indica al servicio web, que entiende su formato hypermedia y puede aprovecharlo.

El servicio web por lo tanto, como implementa hypermedia, le devuelve la información de recurso y la información de
hypermedia que puede utilizar el cliente.

Una vez ya ententido la teoría de Api Rest lo siguiente es implementar una Api Rest en Java.