QUE ES API REST

QUE ES APIs REST

En esta entrada voy a resumir los conceptos más importantes que he tratado en mis ponencias sobre REST.

¿Qué es REST?

REST, REpresentational State Transfer, es un tipo de arquitectura de desarrollo web que se apoya totalmente en el estándar HTTP.

REST nos permite crear servicios y aplicaciones que pueden ser usadas por cualquier dispositivo o cliente que entienda HTTP, por lo que es increíblemente más simple y convencional que otras alternativas que se han usado en los últimos diez 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. Podríamos considerar REST como un framework para construir aplicaciones web respetando HTTP.

Por lo tanto REST es el tipo de arquitectura más natural y estándar para crear APIs para servicios orientados a Internet.

Existen tres niveles de calidad a la hora de aplicar REST en el desarrollo de una aplicación web y más concretamente una API que se recogen en un modelo llamado Richardson Maturity Model en honor al tipo que lo estableció, Leonard Richardson padre de la arquitectura orientada a recursos. Estos niveles son:

  1. Uso correcto de URIs
  2. Uso correcto de HTTP.
  3. Implementar Hypermedia.

Además de estas tres reglas, nunca se debe guardar estado en el servidor, toda la información que se requiere para mostrar la información que se solicita debe estar en la consulta por parte del cliente.

Al no guardar estado, REST nos da mucho juego, ya que podemos escalar mejor sin tener que preocuparnos de temas como el almacenamiento de variables de sesión e incluso, podemos jugar con distintas tecnologías para servir determinadas partes o recursos de una misma API.

Nivel 1: Uso correcto de URIs

Cuando desarrollamos una web o una aplicación web, las URLs nos permiten acceder a cada uno de las páginas, secciones o documentos del sitio web.

Cada página, información en una sección, archivo, cuando hablamos de REST, los nombramos como recursos.

El recurso por lo tanto es la información a la que queremos acceder o que queremos modificar o borrar, independientemente de su formato.

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

Una URL se estructura de la siguiente forma:

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

Por ejemplo, http://asiermarques.com/2013/conceptos-sobre-apis-rest/, sería la URL para visualizar este artículo.

Existen varias reglas básicas para ponerle nombre a la URI de un recurso:

  • 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.

Las URIs no deben implicar acciones y deben ser únicas

Por ejemplo, la URI /facturas/234/editar sería incorrecta ya que tenemos el verbo editar en la misma.

Para el recurso factura con el identificador 234, la siguiente URI sería la correcta, independientemente de que vayamos a editarla, borrarla, consultarla o leer sólo uno de de sus conceptos: /facturas/234

Las URIs deben ser independientes de formato

Por ejemplo, la URI /facturas/234.pdf no sería una URI correcta, ya que estamos indicando la extensión pdf en la misma.

Para el recurso factura con el identificador 234, la siguiente URI sería la correcta, independientemente de que vayamos a consultarla en formato pdf, epub, txt, xml o json: /facturas/234

Las URIs deben mantener una jerarquía lógica

Por ejemplo, la URI /facturas/234/cliente/007 no sería una URI correcta, ya que no sigue una jerarquía lógica.

Para el recurso factura con el identificador 234 del cliente 007, la siguiente URI sería la correcta: /clientes/007/facturas/234

Filtrados y otras operaciones.

Para filtrar, ordenar, paginar o buscar información en un recurso, debemos hacer una consulta sobre la URI, utilizando parámetros HTTP en lugar de incluirlos en la misma.

Por ejemplo, la URI /facturas/orden/desc/fecha-desde/2007/pagina/2 sería incorrecta ya que el recurso de listado de facturas sería el mismo pero utilizaríamos una URI distinta para filtrarlo, ordenarlo o paginarlo.

La URI correcta en este caso sería:

/facturas?fecha-desde=2007&orden=DESC&pagina=2

Nivel 2: HTTP

Conocer bien HTTP no es opcional para un desarrollador web al que le importe su trabajo. Aunque el RFC es sencillo de leer, si estás interesado en aprender bien las bases de este protocolo es muy recomendable la guía de O’Reilly sobre el mismo.

Para desarrollar APIs REST los aspectos claves que hay que dominar y tener claros son:

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

Métodos.

Como hemos visto en el anterior nivel, a la hora de crear URIs no debemos poner verbos que impliquen acción, aunque queramos manipular el recurso.

Para manipular los recursos, HTTP nos dota de los siguientes métodos con los cuales debemos operar:

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

Por ejemplo para un recurso de facturas.

GET /facturas Nos permite acceder al listado de facturas

POST /facturas Nos permite crear una factura nueva

GET /facturas/123 Nos permite acceder al detalle de una factura

PUT /facturas/123 Nos permite editar la factura, sustituyendo la totalidad de la información anterior por la nueva.

DELETE /facturas/123 Nos permite eliminar la factura

PATCH /facturas/123 Nos permite modificar cierta información de la factura, como el número o la fecha de la misma.

Quizá debido al desconocimiento o el soporte de ciertos navegadores, los desarrolladores web han usado, durante los últimos años, únicamente los métodos GET Y POST para realizar todas estas acciones. Si trabajamos con REST, esto sería un error de base y puede darnos problemas incluso a la hora de nombrar nuestros recursos, obligándonos a poner verbos en las URLs.

Códigos de estado.

Uno de los errores más frecuentes a la hora de construir una API suele ser el reinventar la rueda creando nuestras propias herramientas en lugar de utilizar las que ya han sido creadas, pensadas y testadas. La rueda más reinventada en el desarrollo de APIs son los códigos de error y códigos de estado.

Cuando realizamos una operación, es vitar saber si dicha operación se ha realizado con éxito o en caso contrario, por qué ha fallado.

Un error común sería por ejemplo:

Petición
========
PUT /facturas/123
Respuesta
=========
Status Code 200
Content:
{
success: false,
code: 734,
error: “datos insuficientes”
}

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

Este es un error común que tiene varios inconvenientes:

  • No es REST ni es estándar.
  • El cliente que acceda a este API debe conocer el funcionamiento especial y cómo tratar los errores de la misma, por lo que requiere un esfuerzo adicional importante para trabajar con nosotros.
  • Tenemos que preocuparnos por mantener nuestros propios códigos o mensajes de error, con todo lo que eso supone.

HTTP tiene un 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.

Es imperativo conocerlos y saber cuándo utilizarlos, independientemente de que desarrolles siguiendo REST.

El siguiente ejemplo sería correcto de la siguiente forma:

Petición
========
PUT /facturas/123
Respuesta
=========
Status Code 400
Content:
{
message: "se debe especificar un id de cliente para la factura"
}

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.

En la respuesta, se devolverá el header Content-Type, para que el cliente sepa qué formato se devuelve, por ejemplo:

Petición
========
GET /facturas/123
Accept: application/epub+zip , application/pdf, application/json
Respuesta
=========
Status Code 200
Content-Type: application/pdf

En este caso, el cliente solicita la factura en epub comprimido con ZIP y de no tenerlo, en pdf o json por orden de preferencia. El servidor le devuelve finalmente la factura en pdf.

Nivel 3: Hypermedia.

A pesar de lo que nos pueda inducir a pensar el término retrofuturista Hypermedia, el concepto y la finalidad que busca describir es bastante sencillo: conectar mediante vínculos las aplicaciones clientes con las APIs, permitiendo a dichos clientes despreocuparse por conocer de antemano del cómo acceder a los recursos.

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:

666
Procesado

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


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:

666
Procesado

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


Como vemos, el cliente solicita el formatoapplication/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.

Hypermedia es útil por ejemplo para que el cliente no tenga que conocer las URLs de los recursos, evitando tener que hacer mantenimientos en cada uno de los mismos si en un futuro dichas URLs cambian (cosa que no debería pasar). También es útil para automatizar procesos entre APIs sin que haya interacción humana.

Conclusión

Como hemos visto, los principios básicos para construir APIs REST se basan en conocer sobre todo HTTP, algo que no es opcional para un desarrollador web.

SERVER PORTATIL EN UN USB

SERVER2GO , Servidor Web Portátil

Server2Go es un servidor web portable que puede ser ejecutado desde un USB, un CD/DVD-Romo cualquier carpeta del disco duro sin necesidad de instalación, lo cual es bastante útil.

Además, gracias a este servidor portátil, no tendremos que molestarnos en configurar un administrador PHP, Apache o MySQL.

Este util servidor se “instala” a partir de un fichero ejecutable, que al ser descomprimido, crea una carpeta donde quedan instaladas las aplicaciones que habíamos seleccionado en la configuración.

Además de su facilidad de instalación, Server2Go, soporta PHP 5, MySQL 5, SQLite y Perl 5.8. Su sistema está basado en Apache y está disponible para Windows (98, XP, Vista y 7), Mac OS X yGNU/Linux.

Las características principales de Server2Go son las siguientes:

  • Es un servidor web basado en Apache, y esto da bastante confianza, ya que Apache nunca defrauda.
  • Soporta las versiones posteriores de Internet Explorer 6, Firefox, Safari, Camino y algunos otros navegadores.
  • Soporta la base de datos SQLite.
  • Detecta automáticamente el nombre del host y el puerto cuando iniciamos el navegador.
  • Se apaga automáticamente cuando se cierra el navegador.
  • Soporta PHP 5 con multiples extensiones instaladas.
  • Soporta Windows 98 y versiones posteriores de éste, Mac OS X y GNU/Linux.

Puedes descargar este completo servidor web portable desde su página web.

Transacciones en Mysql

Para manejar Transacciones se debe utilizar tablas del tipo InnoDB además permite definir reglas de integridad referencial.

Para asegurarnos que tenemos soporte para el tipo de tablas InnoDB podemos ejecutar la siguiente sentencia:
mysql> SHOW VARIABLES LIKE ‘%innodb%';
+———————————+————+
| Variable_name | Value |
+———————————+————+
| have_innodb | YES |
| innodb_additional_mem_pool_size | 1048576 |
| innodb_buffer_pool_size | 8388608 |
| innodb_data_file_path | ibdata:30M |
| innodb_data_home_dir | |
| innodb_file_io_threads | 4 |
| innodb_force_recovery | 0 |
| innodb_thread_concurrency | 8 |
| innodb_flush_log_at_trx_commit | 1 |
| innodb_fast_shutdown | ON |
| innodb_flush_method | |
| innodb_lock_wait_timeout | 50 |
| innodb_log_arch_dir | . |
| innodb_log_archive | OFF |
| innodb_log_buffer_size | 1048576 |
| innodb_log_file_size | 5242880 |
| innodb_log_files_in_group | 2 |
| innodb_log_group_home_dir | . |
| innodb_mirrored_log_groups | 1 |
| innodb_max_dirty_pages_pct | 90 |
+———————————+————+
20 rows in set (0.00 sec)
La variable más importante es por supuesto have_innodb que tiene el valor YES.

Ahora veamos como usar transacciones.
BEGIN;
INSERT INTO innotest VALUES(4);
SELECT * FROM innotest;
+——-+
| campo |
+——-+
| 1 |
| 2 |
| 3 |
| 4 |
+——-+
4 rows in set (0.00 sec)
/* Si en este momento ejecutamos un ROLLBACK, la transacción no será completada, y los cambios realizados sobre la tabla no tendrán efecto*/
mysql> ROLLBACK;
Query OK, 0 rows affected (0.06 sec)

LAMP o LEMP

SERVIDOR LAMP o LEMP

SERVIDOR LAMP o LEMP

  • LAMP (Linux, Apache, MySQL, PHP o Perl – Python)
  • LEMP (Linux, Nginx (pronunciado como Engine X), MariaDB, PHP, Perl o Python).

En los servidores web se utiliza los paquetes denominada LAMP, haciendo el uso de Linux como sistema operativo, Apache como el servidor web, MySQL el gesto de la base de datos y PHP (normalmente el más ocupado) como el lenguaje de programación. Pero hoy en día tenemos diversas alternativas para sustituir dos de esas cosas, empecemos con el gestor de base de datos.

SERVIDOR DE BASE DE DATOS:

Mariadb vs Mysql

Mariadb vs Mysql

Básicamente vemos como MySQL se ha privatizado(SUN a ORACLE), pero eso no es lo peor, lo peor es que no ha avanzado su desarrollo de la manera que muchos lo esperan, y no es de asombro, ya que Oracle no siempre hace lo mejor. Pero nunca se pierde la esperanza, ya que cuando empezaron los problemas vino un salvador, MariaDB, el proyecto open source derivado de MySQL. MariaDB es una excelente alternativa a MySQL por el simple hecho de que esta es de código abierto y tiene un gran apoyo de la comunidad, pero su mejor característica es el hecho de que es igual a MyQSL, lo que proporciona una mudanza sin problemas (un copia y pega basta), pero claro, MariaDB se mejora en algunos puntos en los cuales MySQL ha olvidado. El porque usar MariaDB es claro, es un proyecto libre, que tiene un gran futuro por el simple hecho de lo que es, a diferencia de MySQL, el cual su futuro es incierto.

SERVIDOR WEB:

Tenemos el uso de Apache desde tiempos inmemorables, pero ahora hay nuevas propuestas que puede que muchos quieran probar y no sólo por que son nuevas, si no por que ofrecen algo mejor, me refiero al uso de Nginx. Nginx (pronunciado como “engine X” ) es un servidor web HTTP de código abierto que también incluye servicios de correo electrónico con acceso al Internet Message Protocol(IMAP) y al servidor Post Office Protocol (POP). Además, NGINX está listo para ser utilizado como un proxy inverso. En este modo, NGINX se utiliza para equilibrar la carga entre los servidores back-end, o para proporcionar almacenamiento en caché para un servidor back-end lento. Es usado por compañías como WordPress, Facebook, Hulu entre otras. Ahora bien, Nginx y Apache son servidores web gratuitos y de código abierto multiplataforma.  Apache es un servidor sumamente completo, tiene muchas funciones disponibles, pero lo cierto es que la mayoría de ellas no son usadas. La diferencia principal con Nginx es que este último tiene menos funciones, pero trabaja a mayor velocidad que Apache en el 90% de los casos. Nginx es el mejor servidor web para servir archivos estáticos y con gran cantidad de peticiones, además lo hace teniendo un consumo de memoria considerablemente menor que Apache, dado que no precisa crear un proceso o hilo nuevo para cada pedido que le llega. Tampoco necesitar analizar todos los directorios de un sitio buscando archivos.htaccess, ya que carga las reglas de Rewrite directamente desde su configuración. El reemplazo de Apache por Nginx suele traer muchas ventajas, ya que este último tiene una notable mejora de velocidad (hay que hacer gran énfasis en lo de la velocidad) cuando se trata de distribuir archivos estáticos y también dinámicos. Nginx es mejor para sitios que tienen una mayor cantidad de peticiones. Si manejas en volumen pequeño aun de peticiones te conviene usar Apache, por un tema práctico, ya cuando tu proyecto va tomando más forma es mejor migrar. Se debe considerar que Nginx por ahora solo se puede utilizar en servidores propietarios, ya que la mayoría de los hosting utilizan Apache