API REST

Las API REST se han convertido en una herramienta muy importante para los desarrollos con IoT al permitir conectar servicios entre sí. Vamos a explicar qué son exactamente.

La interfaz de programación de aplicaciones, conocida también por la sigla API, en inglés, application programming interface, es un conjunto de subrutinas, funciones y procedimientos (o métodos, en la programación orientada a objetos) que ofrece cierta biblioteca para ser utilizado por otro software como una capa de abstracción.

Hoy en día la mayoría de las empresas utilizan API REST para crear servicios. Esto se debe a que es un estándar lógico y eficiente para la creación de servicios web. Por poner algún ejemplo tenemos los sistemas de identificación de Facebook, la autenticación en los servicios de Google (hojas de cálculo, Google Analytics, …).

Las APIs forman el pegamento de conexión entre las aplicaciones modernas. Casi todas las aplicaciones utilizan APIs para conectarse con fuentes de datos corporativas, servicios de datos de terceros u otras aplicaciones. La creación de un formato de descripción abierto para los servicios de API que sea neutral para los proveedores, portátil y abierto es fundamental para acelerar la visión de un mundo verdaderamente conectado.

Una API es básicamente una forma de hacer una solicitud a otra aplicación. Por ejemplo, si estamos desarrollando una aplicación y queremos encontrar a las personas que nos siguen en Twitter, podría solicitar esta información a la API de Twitter: “Dame una lista de todas las personas que me siguen”. No hay diferencias si nuestra aplicación está en Ruby, Php, Javascript, etc., y Twitter otro lenguaje porque la API transmite y recibe datos en un formato común (normalmente JSON o XML). Esto permite que dos aplicaciones totalmente separadas envíen y reciban datos.

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

Conocer bien HTTP no es opcional para alguien de desarrollo APIs ni para los consumidores de las mismas. El RFC es sencillo de leer.

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

Métodos HTTP: https://developer.mozilla.org/es/docs/Web/HTTP/Methods
Códigos de estado: https://es.wikipedia.org/wiki/Anexo:C%C3%B3digos_de_estado_HTTP
Aceptación de tipos de contenido: https://developer.mozilla.org/es/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Lista_completa_de_tipos_MIME

Más información:

Según Fielding las restricciones que definen a un sistema RESTful serían:

Cliente-servidor: esta restricción mantiene al cliente y al servidor débilmente acoplados. Esto quiere decir que el cliente no necesita conocer los detalles de implementación del servidor y el servidor se “despreocupa” de cómo son usados los datos que envía al cliente.
Sin estado: aquí decimos que cada petición que recibe el servidor debería ser independiente, es decir, no es necesario mantener sesiones.
Cacheable: debe admitir un sistema de almacenamiento en caché. La infraestructura de red debe soportar una caché de varios niveles. Este almacenamiento evitará repetir varias conexiones entre el servidor y el cliente para recuperar un mismo recurso.
Interfaz uniforme: define una interfaz genérica para administrar cada interacción que se produzca entre el cliente y el servidor de manera uniforme, lo cual simplifica y separa la arquitectura. Esta restricción indica que cada recurso del servicio REST debe tener una única dirección, “URI”.
Sistema de capas: el servidor puede disponer de varias capas para su implementación. Esto ayuda a mejorar la escalabilidad, el rendimiento y la seguridad.

Las operaciones más importantes que nos permitirán manipular los recursos son cuatro:

GET para consultar y leer
POST para crear
PUT para editar
DELETE para eliminar.

Ventajas e inconvenientes de las API REST: http://www.desarrolloweb.com/articulos/ventajas-inconvenientes-apirest-desarrollo.html

Arquitectura de una API REST: https://juanda.gitbooks.io/webapps/content/api/arquitectura-api-rest.html

Buenas prácticas de diseño de API REST: https://elbauldelprogramador.com/buenas-practicas-para-el-diseno-de-una-api-restful-pragmatica/

Qué es REST:

Enlaces:

Cliente REST de Arduino: https://github.com/csquared/arduino-restclient

Requests HTTP en python:

En informática, CRUD es el acrónimo de «Crear, Leer, Actualizar y Borrar» (del original en inglés: Create, Read, Update and Delete), que se usa para referirse a las funciones básicas en bases de datos o la capa de persistencia en un software.

Wikipedia: https://es.wikipedia.org/wiki/CRUD

Crear una API: https://desarrolloweb.com/manuales/manual-desarrollo-api.html

Pulling and pushing data con Arduino usando HTTP:

Pull: Una aplicación en un ordenador o servidor pregunta a Arduino por los datos

Push: Arduino se comunica con el servidor para mandarle los datos

Postman

Postman surgió originariamente como una extensión para el navegador Google Chrome. A día de hoy dispone de aplicaciones nativas para MAC y Windows y Linux.

Está compuesto por diferentes herramientas y utilidades gratuitas (en la versión free) que permiten realizar tareas diferentes dentro del mundo API REST: creación de peticiones a APIs internas o de terceros, elaboración de tests para validar el comportamiento de APIs, posibilidad de crear entornos de trabajo diferentes (con variables globales y locales), y todo ello con la posibilidad de ser compartido con otros compañeros del equipo de manera gratuita (exportación de toda esta información mediante URL en formato JSON).

Además, dispone de un modo cloud colaborativo (de pago) para que equipos de trabajo puedan desarrollar entre todos colecciones para APIs sincronizadas en la nube para una integración más inmediata y sincronizada.

Más información: https://www.paradigmadigital.com/dev/postman-gestiona-construye-tus-apis-rapidamente/

El interés fundamental de Postman es que lo utilicemos como una herramienta para hacer peticiones a APIs y generar colecciones de peticiones que nos permitan probarlas de una manera rápida y sencilla.

Las colecciones son carpetas donde se almacenan las peticiones y que permiten ser estructuradas por recursos, módulos o como desees:

Todas las llamadas almacenadas en nuestra colección pueden ser exportadas a múltiples lenguajes haciendo clic en el apartado Generate Code que podéis ver en la captura anterior. Os dejo un ejemplo de cómo exporta una llamada GET para poder ser utilizada automáticamente desde código Python:

Herramienta para las API REST: Postman

Video explicativo: https://www.youtube.com/watch?list=PLM-7VG-sgbtCJYpjQfmLCcJZ6Yd74oytQ&v=ptvV_Fc3hd8

Como probar una api rest con postman: https://www.luisllamas.es/realizar-peticiones-http-con-postman/

Instalar postman y probar a hacer estas dos peticiones:

Uso de API REST con Node-RED

Para integrar Node-Red con APIs que utilizan el protocolo HTTP debemos usar las HTTP requests/response de Node-RED.

HTTP recipes en Node-RED: https://cookbook.nodered.org/http/

Nodo HTTP request: https://flows.nodered.org/node/node-red-contrib-http-request

NOTA: antes de usar el nodo de HTTP request para acceder a una API pública buscar en https://flows.nodered.org/ si ya se ha publicado el nodo que lo haga. Por ejemplo https://flows.nodered.org/node/node-red-node-openweathermap

HTTP requests

HTTP request para novatos: http://www.steves-internet-guide.com/node-red-http-request-node-beginners/

Autorización/Autenticación API Rest

En el mundo de las API REST, se deben implementar flujos distintos de los habituales en cuanto a la autenticación de usuarios, ya que su arquitectura nos ofrece otro tipo de recursos que los tradicionales. Por lo general, en las aplicaciones web tradicionales, se utilizan las variables de sesión como soporte para memorizar el usuario. Esto viene a decir que en el momento de autenticar un usuario, el servidor genera las correspondientes variables de sesión y en las siguientes páginas consultadas por ese mismo cliente, es capaz de recordar al usuario.

Sin embargo, en las aplicaciones REST, esto no es posible, ya que una de las limitaciones de este sistema es que no se dispone de variables de sesión. Esto es debido a motivos de escalabilidad, ya que las API REST suelen estar alojadas en un cluster de servidores. La solución habitual para salvar este problema es la autenticación por token.

Una API RESTful debería ser stateless (sin estado). Esto significa que la petición de autenticación no debería depender de cookies o sesiones. En lugar de ello, cada petición debería venir con algún tipo de credencial de autorización.

En una API REST, enviar las credenciales una vez para iniciar sesión no es suficiente, las API REST son asíncronas. Al ser asíncrona, la API REST no puede recordar las credenciales ya que no existe ninguna sesión activa HTTP. ¡Así que tienes que indicar quién eres cada vez que hagas una petición!

Siempre que se use SSL, las credenciales de autenticación pueden ser simplificadas a un token de acceso generado de forma aleatoria, que es entregado en el campo de nombre de usuario de HTTP Basic Auth.

De todos modos, este método de autenticación token-over-basic-auth (token sobre autenticación básica) es sólo aceptable en los casos en que sea práctico tener la posibilidad de que el usuario copie un token de una interface de administración del entorno del consumidor de la API.

En los casos donde no sea posible, OAuth 2 debería ser usado para facilitar la transferencia del token seguro a terceros. OAuth 2 usa tokens Bearer y además depende de SSL para su encriptación de transporte subyacente.

Una API que necesita soporte JSONP necesitará un tercer método de autenticación, ya que las peticiones JSONP no pueden enviar credenciales HTTP Basic Auth ni Bearer tokens. En este caso, puede utilizarse un parámetro especial de consulta “access_token”.

Más información:

Basic Auth

Esta es la forma más sencilla de asegurar tu API. Se basa principalmente en un nombre de usuario y una contraseña para identificarte.

Para comunicar estas credenciales desde el cliente hasta el servidor, se debe realizar mediante el encabezado HTTP Autorización (Authorization), según la especificación del protocolo HTTP.

Este método de autentificación está algo anticuado y puede ser un problema de seguridad en tu API REST.

API Key

Las API Keys son el primer método que apareció para realizar accesos a este tipo de servicios. Los desarrolladores no dudan en pensar en ella como la primera alternativa a la hora de autenticarse en su API. Esto se debe a que entre sus ventajas están su simpleza, la posibilidad de sacar estadísticas de accesos o peticiones y a su facilidad de uso para implementarlas en las aplicaciones que consumirán el servicio. Generalmente cuando accedemos a una web con este tipo de autenticación, vamos a nuestro perfil y en la sección de configuración nos encontramos con la API Key lista para ser cargada en alguna app móvil o servicio web para hacer tests de API.

Todo esto trae aparejados dos grandes problemas que son: su falta de seguridad y la pésima experiencia de usuario. En muchos casos, estas claves son enviadas dentro de la URL en donde se realiza la petición al servicio, lo que permite ser accedida por alguien que no debería. Para esto el estándar nos dice que las keys deberían viajar en el Header de la petición, para dificultar un poco su acceso por parte de terceros, aunque en la práctica se pueden ver en el Header Authorization, en un Header personalizado o en la URL.

Token

Un token es un valor que nos autentica en el servidor, Normalmente se consigue después de hacer login mediante usuario/contraseña.

Un token se genera normalmente como un hash calculado con algún dato (p.ej. login del usuario + clave secreta). Además el token puede llevar datos adicionales como el login.

Cada vez que el cliente deba realizar nuevas solicitudes al servidor, certificando que es un usuario correctamente autenticado, tendrá que enviar el token de nuevo al servidor. Por lo tanto, una vez recibido el token, deberá ser almacenado del lado del cliente para enviarlo con las posteriores solicitudes. En estos casos, el token suele viajar en las cabeceras del HTTP, de modo que llegue al servidor.

El servidor que recibe el token tiene la capacidad de desencriptarlo, de modo que pueda comprobar qué usuario es el que está realizando esta solicitud. Durante el proceso de decodificación del token, el servidor puede comprobar si este es válido y si resulta serlo, puede recuperar toda la información encriptada en el mismo, que suele ser al menos la referencia inequívoca del usuario involucrado. Por supuesto, si en cualquier momento se detecta que el token no es correcto, se obligará al usuario a autenticarse nuevamente.

Más información: https://desarrolloweb.com/articulos/autenticacion-token.html

JSON Web Token

Este tipo de token es mucho más largo que los demás ya que depende de la cantidad de datos que queramos almacenar en él. Sin embargo, una buena utilización del mismo nos permitiría mantener un token que se puede enviar por la red sin ocupar mucho espacio.

Este token está compuesto por varios campos codificados en base64 donde se guarda la información, identificación de usuario, alcance de los permisos del token, y finalmente una firma de todo los datos contenidos del token hecha por el servidor de la API para comprobar que el token es válido. Esta comprobación es mucho más eficiente y rápida que el acceso a la base de datos para determinar a quién pertenece, qué permisos tiene, etc.

OAuth 2

Con frecuencia, cuando se habla de seguridad y de OAuth, los conceptos de autenticación y autorización se solapan y son completamente diferentes:

La autenticación se define como el proceso mediante el cual se verifica quién eres, es decir, su ámbito se refiere a la identificación.
La autorización es el proceso mediante el cual se verifica a qué tienes acceso, es decir, su ámbito se limita al control de acceso.

Atendiendo a esos conceptos, OAuth es un framework que permite delegar la autorización de acceso a las APIs, NO es un protocolo de autenticación. Para que una app pueda acceder a servicios de terceros sin que el usuario tenga que darle a la app sus credenciales del servicio. Se basa en el uso de un token de sesión.

Este método es el mejor para las APIs que contengan información de usuarios. ¿Por qué? Principalmente por ser la más robusta de las tres alternativas y por cómo está definido el protocolo OAuth nos posibilita declarar permisos para cada aplicación que quiere acceder a la API y así tener varios tipos de autorización para apps diferentes.

Las implementaciones de OAuth utilizan uno o los dos tokens siguientes:

Token de acceso: se envía como una API key, permite acceder a la información del usuario. Opcionalmente pueden tener una expiración.
Token de refresco: son un token opcional que sirve para actualizar el token de acceso en caso de que éste haya expirado.

Más información:

WebHooks

Un Webhook es una manera de ser notificado cuando un evento ha ocurrido en tu aplicación o la de un tercero. Es básicamente una solicitud POST que se envía a una URL específica. Esa URL está configurada para recibir el cuerpo de la solicitud POST y procesarla de alguna manera.

Una API se utiliza para hacer preguntas directas y un Webhook se utiliza para notificar cuando se producen ciertos eventos. En lugar de preguntar constantemente si algo ha cambiado, un webhook puede activarse y notificarnos automáticamente apenas se produzca el evento.

API está haciendo cosas cuando se lo pides, mientras que Webhook hace cosas propias cuando ciertos criterios coinciden.

La principal diferencia entre el funcionamiento de los Webhooks y las APIs es que, mientras que las APIs realizan llamadas sin saber si reciben alguna actualización de datos como respuesta o no, los Webhooks reciben llamadas a través de HTTP POSTs desde sistemas externos sólo cuando éstos tienen algunas actualizaciones de datos.

Por otro lado, los Webhooks son llamadas automáticas de example.com a un servidor. Estas llamadas se activan cuando ocurre un evento específico en example.com. Por ejemplo, si un nuevo usuario se registra en example.com, la llamada automática puede configurarse para pedir al servidor que envíe un correo electrónico de bienvenida.

Si empezamos a pensar más en Webhooks, podemos empezar a ver a todos los Web Services como un gran repositorio de librerías asíncronas. Con el uso de Webhooks podemos por ejemplo pensar en implementar notificaciones en tiempo real sin necesidad de estar haciendo polling.

Un webhook no es una API, no es una tecnología, es solo un patrón de diseño donde definimos hooks que pueden ser invocados por terceros vía HTTP. Simple y Elegante. Esto es muy fácil implementarlo en Arduino.

Más información:

WebHooks IFTTT

Son webhooks para luego lanzar otros servicios: https://ifttt.com/maker_webhooks

Para disparar un evento, hacer un POST o GET a: https://maker.ifttt.com/trigger/{event}/with/key/aaabbbcccdddeee con un cuerpo JSON opcional con el formato: { «value1» : «», «value2» : «», «value3» : «» }

Ejemplo de APIS

API Telegram: https://core.telegram.org/bots/api

API Twitter: https://developer.twitter.com/en/docs

API thingspeak: https://www.mathworks.com/help/thingspeak/

API Rest con Arduino

Práctica: API AEMET

Documentación: https://opendata.aemet.es/dist/index.html?

Predicción municipio horaria: https://opendata.aemet.es/dist/index.html?#!/predicciones-especificas/Predicci%C3%B3n_por_municipios_horaria_Tiempo_actual

Código Logroño: 26089

Práctica: Conexión a Thingspeak

Escribir datos en un canal: https://es.mathworks.com/help/thingspeak/write-data.html

Detalles: https://es.mathworks.com/help/thingspeak/writedata.html

Práctica: Conexión a EmonCMS

Documentación API: https://emoncms.org/site/api

Aprendiendo Arduino

Aprendiendo a manejar Arduino en profundidad