Category: Programación

Aumentar espacio de tu Raspberry Pi usando un dispositivo de almacenamiento USB

Una de las bondades de los sistemas GNU/Linux es la posibilidad de montar una unidad USB y  formatearla convenientemente. La cual puede ser montada a voluntad o meterla en la fstab (File Systems TABle) para que se monte con el arranque del sistema si lo deseamos. Para estas cosas GNU/Linux es la caña y es super flexible!! 😉

Un opción que podría ejemplificar fácilmente el uso de este procedimiento, puede ser una Raspberry Pi a la que queráis darle más espacio que el que tenéis disponible en la microSD donde tenéis montado el sistema operativo. Actualmente las memorias USB han bajado mucho su precio y han aumentado los tamaños máximos de las mismas, encontrándonos a precios razonables memorias de 128GB o256GB.

Empecemos con lo básico que es conectar la memoria USB a la Rapsberry Pi (obvio pero por si acaso lo digo 😉 ). Con la memoria USB conectada ejecutamos el siguiente comando:

ls -l /dev/disk/by-uuid/

El comando nos responde identificado las unidades disponibles. Las unidades “mmcblk0p1” y “mmcblk0p2” corresponden a la partición de boot del la Rapsberry Pi y a la de ficheros de Raspbian (Sistema Operativo) respectivamente. La que nos insteresa es la “sda1“. Anota el identificador (UUID) que tiene, en mi ejemplo el mio es “51a4dc12-f769-4286-bdb6-58f40f6a7ce2“.

Ahora vamos a preparar el punto de montaje de la unidad. Para ello ejecuta el siguiente comando para crear la ruta “media/usb” donde montaremos la unidad:

sudo mkdir /media/usb

Puedes usar otra ruta si lo deseas, pero intenta que sea corta, ya que tendrás que escribirla tantas veces como quieras acceder a la unidad.

Ahora hay que asegurarnos que el usuario “pi” es propietario de la nueva carpeta donde montaremos la unidad. Para ello ejecuta:

sudo chown -R pi:pi /media/usb

Para montar la unidad lo haremos con el siguiente comando:

sudo mount /dev/sda1 /media/usb

Si ejecutamos el comando:

df -h -T

Veremos que aparece la unidad en el punto de montaje “media/usb” indicado, así como el tipo de sistema de ficheros. Si has usado otro punto de montaje, aparecerá que el que hayas puesto.

Como usar la memoria USB con el formato FAT32 (aparece como vfat) no es lo más óptimo, formatearemos la unidad a EXT4 mucho más óptimo para nuestro sistema Raspbian. Puedes formatear fácilmente la unidad con el siguiente comando tras desmontar la unidad con:

sudo umount /media/usb
sudo mkfs.ext4 /dev/sda

⚠️ Ten en cuenta que si ejecutas los comandos para formatear la memoria USB, perderás los datos que hubiese dentro. ⚠️ Si estamos conformes con el formateo decimos que sí.

Si quisiéramos que la unidad se montase automáticamente, tendremos que incluir la nueva unidad en fstab. Para ello abriremos primero el fichero de configuración de fstab:

sudo nano /etc/fstab

Y añadiremos tras la última línea esta otra:

UUID=51a4dc12-f769-4286-bdb6-58f40f6a7ce2 /media/usb ext4 auto,nofail,noatime,users,rw 0 0

El parámetro más importante es el “UUID” que anotamos al principio del artículo. Si finalmente optaste por formatear la memoria USB a EXT4, te recomiendo que vuelvas a ejecutar el comando porque el valor habrá cambiado.

Para concer específicamente el significado de cada parámetro te dejo la siguiente referencia:

Si finalmente decidiste NO formatear la memoria USB, la línea cambia un poco y se sustituye “ext4” por “vfat“:

UUID=51a4dc12-f769-4286-bdb6-58f40f6a7ce2 /media/usb ext4 auto,nofail,noatime,users,rw 0 0

Ahora solo nos resta comprobar si efectivamente la unidad se monta sola y para ello ejecutaremos un reinicio:

reboot

Si lo hemos hecho bien deberíamos poder ver la memoria USB en “/media/usb“. Ya tenemos más espacio en nuestra Raspberry Pi!! 😉

Configurar servidor DNS caché con tu Raspberry Pi para mejorar la velocidad del Tráfico de tu Red Local

Un de las piezas claves hoy en día de nuestro Internet que permite que funcione, son las Domain Name System o mayormente conocido como DNS. Este sistema de servidores DNS es el encargado de traducir los nombres de dominio que manejamos habitualmente, como mascandobits.es, en la dirección IP del ordenador donde está alojado ese dominio, que en el momento de escribir esta entrada es 31.220.20.199 .

 

Contextualización


Cada ordenador en Internet tiene una dirección IP que es única para ese ordenador (por lo menos en la red que pertenece). La IP está formada por cuatro números enteros de 0 a 255, separados por puntos. 127.0.0.1 es un ejemplo de dirección IP que además es especial porque hace referencia a nuestra propia máquina. Cada vez que te conectas a Internet, a tu ordenador se le asigna una dirección IP, puede ser siempre la misma o puede variar, lo normal es que cada vez que reinicies el router o al cabo de un tiempo obtengas una IP diferente.

Esta IP que tiene tu equipo, y que te proporciona tu router, es privada y solo funciona en el rango de tu red local (dispositivos conectados a tu router). Existe un conjunto de rangos de IP que son usados como IPs privadas:

  • 192.168.0.0 – 192.168.255.255 (65,536 direcciones IP)
  • 172.16.0.0 – 172.31.255.255 (1,048,576 direcciones IP)
  • 10.0.0.0 – 10.255.255.255 (16,777,216 direcciones IP)

El primer grupo de IPs lo puedes ver en la red local de tu casa o empresa (si es pequeña), el segundo grupo en empresas algo más grandes y el último grupo es común verlo para equipos conectados mediante VPN.

A su vez existe una segunda IP denominada pública que es la que tu ISP o proveedor de servicios te asigna al router y que sirve para poder acceder a Internet. Esta IP pública suele ser dinámica en la mayor parte de los casos y tu ISP se la asigna a tu router, normalmente reiniciando el router puede cambiar esta IP.

La conversión de una IP privada a una pública y viceversa se hace gracias a la Network Address Translation o NAT del router. Esto permite hacer peticiones a IPs publicas de servicios de Internet y devolver el tráfico de respuesta a la IP privada de la máquina que hizo las peticiones.

Un vez aclarado esta parte que es básica avancemos….

Los ordenadores donde están alojadas las páginas web o servicios tienen siempre la misma dirección IP, esto permite acceder dichos recursos siempre igual con la misma IP (a no ser que se cambie…). Sin embargo, cuando buscas una determinada página o servicios, en tu navegador no introduces la IP del ordenador donde está alojada, sino algo más sencillo de recordar, introduces un nombre de dominio, como mascandobits.es. Adicionalmente he dicho que normalmente no se cambia la IP de la web o servicio, pero puede darse el caso por ejemplo de que se quiera mover la web o servicio a otra máquina que muy seguramente tenga otra IP pública.  Gracias a las DNS este problema queda cubierto, ya que simplemente basta con asociar el dominio con la nueva IP pública.

Cuando escribes en tu navegador el nombre de una web o servicio, lo que hace tu ordenador es preguntar a tu servidor local DNS (el que te indica tu router por DCHP) por la dirección IP del ordenador donde está alojada esa página o servicio. El servidor DNS es una gran base de datos con infinidad de traducciones de nombres de dominio a dirección IP. Esa base de datos es distribuida y compartida con otros proveedores y sus respectivos servidores DNS. Si el nombre de dominio que estás buscando no está en tu DNS local, éste realizará una petición a otros DNS de la red hasta encontrar la traducción adecuada. Estas bases de datos guardan en caché durante unos días esas traducciones de nombre de dominio a IP, por eso a veces sucede que si una web o servicio cambia de servidor, puede que desde algunos lugares del planeta se acceda a la web o servicio y desde otros no, porque hay ordenadores que cuando preguntan por la página, el servidor DNS los envía a la antigua dirección IP y no a la nueva.

Además de los servidores DNS, nuestro ordenador también guarda un caché de las DNS, y si hemos visitado recientemente una página web, nuestro ordenador ya no preguntará al servidor cuál es la dirección IP de la página, sino que se dirigirá a la que ya tiene almacenada. Esta caché puede borrarse.

Para borrarla desde Windows:

ipconfig /flushdns

Para borrarla desde GNU-Linux:

sudo /etc/init.d/nscd restart  //si usas nscd dns cache
sudo /etc/init.d/dnsmasq restart  //si usas dnsmasq dns cache
sudo /etc/init.d/named restart  //si usas bind dns cache
sudo /etc/init.d/bind9 restart  //(alternativa) si usas bind dns cache

 

Configurar servidor DNS caché


Las DNS constituyen la columna vertebral del funcionamiento de Internet y dado su función constituye un riesgo una mala gestión de los DNS globales que son gestionados por la ICANN, una asociación sin ánimo de lucro. Existen 7 llaves que dan acceso físico a los DNS y que se reparten entre 14 personas, 7 titulares y 7 suplentes. Son los garantes de que los DNS no sean atacadoso o modifcados de manera no deseada:

Como puedes deducir el acceso a la resolución de DNS es algo que puede ser muy crítico. La ICANN sólo constituye el registro de una parte de Internet, aunque habitualmente se suelen usar sus DNS como referencia, ya que a su vez las operadoras que dan acceso a Internet (ISP) tienen sus propio DNS que van configurados en nuestro router y los cuales podemos cambiar por otros que sean de nuestro agrado.

Controlar las DNS y cómo se resuelven es algo que puede ser ventajoso, sobre todo si tenemos dentro de nuestra red local el servidor DNS y la resolución de dominios tiene una menor latencia. Para crear nuestro DNS caché lo podemos hacer con una Raspberry Pi conectada a nuestra red local de casa. Una Raspberry Pi consume como un móvil cargando y puede servirnos perfectamente para este cometido de acelerar las peticiones de resolución de DNS.

Accedemos a nuestra Raspberry Pi por SSH e introducimos el siguiente comando:

sudo apt-get install bind9 dnsutils

Con esto instalamos bind y además instalamos la herramienta dig (con el paquete dnsutil) que más adelante ya veréis para qué sirve.

Un vez instalado vamos a /etc/bind/named.conf.options, puedes configurarlo con el siguiente comando:

sudo nano /etc/bind/named.conf.options

Lo puedes configurar con la siguiente información:

    forwarders {
         208.67.222.222;
         208.67.220.220;
    };

Es posible que tengas que quitar la // para que tenga efecto. Todo lo que va precedido con // se trata como un comentario. Yo he usado como forwarders las DNS de OpenDNS, pero puedes usar las que quieras o añadir otras.

Ahora recargamos las configuraciones con el siguiente comando:

rndc reload

Ya tenemos funcionando nuestro servidor DNS cacche. Para comprobar la diferencia de tiempos de resolución vamos a hacer la siguiente prueba. Vamos a resolver las peticiones contra las DNS de Google (8.8.8.8) (se asume que son de lo mejorcito 😉 ) y contra nuestro nuevo servidor DNS caché en la Raspberry Pi.

Introducimos el siguiente comando para comprobar el tiempo de respuesta para la resolución del dominio mascandobits.es con las DNS de Google:

dig mascandobits.es  @8.8.8.8

; <<>> DiG 9.9.5-9+deb8u13-Raspbian <<>> mascandobits.es @8.8.8.8
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 28184
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 512
;; QUESTION SECTION:
;mascandobits.es.               IN      A

;; ANSWER SECTION:
mascandobits.es.        2684    IN      A       31.220.20.199

;; Query time: 42 msec
;; SERVER: 8.8.8.8#53(8.8.8.8)
;; WHEN: Thu Oct 26 19:11:51 CEST 2017
;; MSG SIZE  rcvd: 60

Nos devuelve 42 msec, que no está anda mal, pero vamos a ejecutar lo mismo usando nuestro DNS de la Raspberry Pi. Lo haremos dos veces, ya que la primera vez le costará un tiempo similar, o algo mayor, ya que deberá ir a buscar la resolución del dominio a los forwarders que configuramos la primera vez, en mi caso a los DNS de OPenDNS. Para la segunda ejecución os debería salir algo así:

dig mascandobits.es  @127.0.0.1

; <<>> DiG 9.9.5-9+deb8u13-Raspbian <<>> mascandobits.es @127.0.0.1
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 59435
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 7, ADDITIONAL: 14

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4096
;; QUESTION SECTION:
;mascandobits.es.               IN      A

;; ANSWER SECTION:
mascandobits.es.        2575    IN      A       31.220.20.199

;; AUTHORITY SECTION:
es.                     146250  IN      NS      a.nic.es.
es.                     146250  IN      NS      ns-ext.nic.cl.
es.                     146250  IN      NS      ns1.cesca.es.
es.                     146250  IN      NS      f.nic.es.
es.                     146250  IN      NS      ns3.nic.fr.
es.                     146250  IN      NS      sns-pb.isc.org.
es.                     146250  IN      NS      g.nic.es.

;; ADDITIONAL SECTION:
a.nic.es.               146250  IN      A       194.69.254.1
a.nic.es.               146250  IN      AAAA    2001:67c:21cc:2000::64:41
f.nic.es.               146250  IN      A       130.206.1.7
f.nic.es.               146250  IN      AAAA    2001:720:418:caf1::7
g.nic.es.               146250  IN      A       204.61.217.1
g.nic.es.               146250  IN      AAAA    2001:500:14:7001:ad::1
ns1.cesca.es.           146250  IN      A       84.88.0.3
ns1.cesca.es.           146250  IN      AAAA    2001:40b0:1:1122:ce5c:a000:0:3
ns3.nic.fr.             146250  IN      A       192.134.0.49
ns3.nic.fr.             146250  IN      AAAA    2001:660:3006:1::1:1
ns-ext.nic.cl.          146250  IN      A       200.1.123.14
sns-pb.isc.org.         146250  IN      A       192.5.4.1
sns-pb.isc.org.         146250  IN      AAAA    2001:500:2e::1

;; Query time: 1 msec
;; SERVER: 127.0.0.1#53(127.0.0.1)
;; WHEN: Thu Oct 26 19:11:40 CEST 2017
;; MSG SIZE  rcvd: 495

Hemos bajado a 1 msec, que es bastante mejor que el tiempo de las DNS de Google. Además esto nos demuestra que se consigue bastante velocidad, en mi caso 42 veces más rápido para un dominio cacheado previamente por el servidor DNS de la Raspberry Pi.

Ahora para que todos los dispositivos de tu red usen estas nuevas DNS, lo más fácil es configurarlo en el router. Yo tengo un router de TP-Link, pero la configuración suele ser similar en todos los routers. Lo que nos interesa suele estar en la sección “DCHP”:

En el DNS Server he añadido la IP de la Raspberry Pi donde está el servidor DNS, es recomendable para ello que asignes IP estática a la Raspberry Pi. Hoy en día lo puedes hacer fácil desde el propio router asociando una IP privada a la MAC de la Raspberry Pi. El Secondary DNS Server lo he dejado con 0.0.0.0 para que lo resuelva contra el modem-router de proveedor de servicio a Internet (ISP). Esto hace que si la Raspberry Pi deja de funcionar, la red puede seguir resolviendo los dominios contra las DNS que me proporciona el router de mi ISP. Hay que cubrirse siempre 😉 !.

Con esto ya estaría listo, pero para dejarlo todo bien atado vamos a volver a la consola SSH de la Raspberry Pi para comprobar si bind arrancará al inicio si la apagas y enciendes. Para ello vamos a introducir el siguiente comando:

service bind9 status
● bind9.service - BIND Domain Name Server
   Loaded: loaded (/lib/systemd/system/bind9.service; enabled)
  Drop-In: /run/systemd/generator/bind9.service.d
           └─50-insserv.conf-$named.conf
   Active: active (running) since jue 2017-10-26 10:25:49 CEST; 5h 18min ago
     Docs: man:named(8)
 Main PID: 17478 (named)
   CGroup: /system.slice/bind9.service
           └─17478 /usr/sbin/named -f -u bind

Si en la línea de “Loaded” vemos al final “enabled”es que está activado como servicio al arranque. Si no fuera así bastaría con ejecutar el siguiente comando:

sudo systemctl enable bind9

Si quieres ver de manera general todos los servicios que tienes corriendo puedes ejecutar:

service --status-all

Podremos ver los servicios que existen y si están arrancados o no.

Con esto ya queda tu red perfectamente configurada para usar tu propio servidor DNS caché alojado en tu Rapsberry Pi para toda tu red local y mejorar los tiempos de respuesta de la resolución de dominios.

 

Resetear contraseña olvidada de tu Raspberry Pi

La semana pasada me encontré con el problema de tener que acceder vía SSH a una Raspberry Pi (rpi), para poder gobernar una serie de maquinas accesibles desde la red local a la que se conectaba dicha rpi, y no poder hacerlo porque no recordaba la contraseña…

Al ver que no recordaba la contraseña me puse a buscar la mejor solución para poder volver a tener acceso a la rpi. Alguno puede pensar que con volver a poner el sistema operativo Raspbian, queda todo solucionado, y tiene razón. El problema, es que toda la configuración y software específico se borra, teniendo que volver a cargar el sistema operativo, instalar el software y generar de nuevo las configuraciones… vamos un peñazo XD .

Alguno se le ocurriría montar un script en el que ir probando las posibles combinaciones por fuerza bruta. En mi caso no era una opción, ni suele serlo en general. Con que cumplas los criterios básicos de una contraseña decente la combinatoria se dispara… Los tiempos en los que las claves eran de hasta 6 caracteres normalmente sólo letras y/o números han quedado atrás.

Con todo ello en mente le di alguna vuelta más al asunto…

Me puse a pensar cuál es nivel de seguridad que me podría permitir resetear la clave, y pronto caí que en el físico. Tenía acceso físico al hardware de la rpi, con lo que cogí la tarjeta SD y la introduje en mi ordenador. En su interior enseguida encontré un archivo, que mirando un poco en Internet, entendí que me podía dar la clave para poder acceder al sistema antes de que completamente se cargase y me obligase a idetificarme con las credenciales de acceeso, de la cual había perdido la contraseña.

El fichero en cuestión es el “cmdline.txt” y contiene parámetros específicos para la carga del kernel de Raspbian:

dwc_otg.lpm_enable=0 console=ttyAMA0,115200 kgdboc=ttyAMA0,115200 console=tty1 root=/dev/mmcblk0p2 rootfstype=ext4 elevator=deadline rootwait

Según la documentación es posible cargar la ejecución de cualquier binario con el parámetro “init“, y en este caso nos interesa cargar la shell. Para ello añadimos “init=/bin/sh” al final de la línea precedido por un espacio:

dwc_otg.lpm_enable=0 console=ttyAMA0,115200 kgdboc=ttyAMA0,115200 console=tty1 root=/dev/mmcblk0p2 rootfstype=ext4 elevator=deadline rootwait init=/bin/sh

Hecha esta modificación en el fichero lo guardamos, volvemos a introducir la SD en la rpi y la arrancamos. Esta vez durante el arranque, se parará en cierto momento la carga del sistema y nos aparecerá un prompt en el que podremos escribir comandos.

Antes de escribir cualquier comando debemos remontar el volumen para que efectivamente guarde los cambios. Para ello vamos a volver a montar el sistema de ficheros como lectura y escritura con el siguiente comando.

mount -rw -o remount /

Una vez hecho, vamos a invocar al comando que nos permite resetear la contraseña de nuestro usuario (normalmente pi si no los has cambiado):

passwd pi

Te pedirá que introduzcas la contraseña y otra vez más para confirmarla. Si todo ha ido bien verás un mensaje de este tipo:

passwd: password updated successfully

Ahora sincronizaremos los cambios que hemos hecho que están en memoria, para que queden persistentes en la memoria de la SD. Después reanudaremos el boot del sistema:

sync
exec /sbin/init

Una vez se haya cargado el sistema comprueba que puedes acceder con la clave que intruduciste y apaga la rpi con:

sudo poweroff

Una vez apagada la rpi volvemos a cargar la SD en el ordenador y editamos de nuevo el fichero “cmdline.txt” y lo volvemos a dejar como al inicio sin el parámetro “init“:

dwc_otg.lpm_enable=0 console=ttyAMA0,115200 kgdboc=ttyAMA0,115200 console=tty1 root=/dev/mmcblk0p2 rootfstype=ext4 elevator=deadline rootwait

Ahora ya podemos volver a poner la tarjeta SD en la Raspberry Pi y podremos volver a tener el sistema Raspbian como si nunca hubiéramos perdido la contraseña.

Recordad que esto ha sido posible gracias a tener acceso físico al hardware que ejecuta el software. El nivel físico siempre es el nivel más débil a nivel técnico y de infraestructura, por eso en Seguridad Informática hay que cuidar no sólo a quién damos acceso mediante credenciales, sino también quién tiene acceso físicamente al hardware donde se corre el software.

Buenas Prácticas para el Buen Diseño de una API RESTful

Según pasa el tiempo y vas haciendo servicios que tienen que escalarse e integrarse con otros servicios, te vas dando cuenta de lo necesario que es un buen diseño o por lo menos de un diseño mínimamente bien pensando y ejecutado que cumpla una serie de requisitos mínimos. Ésta es la idea que pretendo transmitiros, pero antes os ubico un poco.

En la entrada de Linkero – Creación de APIs RESTful en Python os presenté el framework Linkero que permitía montar APIs RESTful, y se presentaba junto con un ejemplo a forma de iniciación en las mismas.  En este entrada voy presentar una serie de recomendaciones, que pueden considerarse beunas prácticas, y que debéis tener en cuenta para asegurar un buen diseño de vuestras APIs RESTful.

El concepto subyacente de una API RESTful es la de dividir la estructura de la API en recursos lógicos, montados sobre una URL, que nos permitan acceder a información o datos concretos usando métodos HTTP como POST, GET, PUT y DELETE para operar con los recursos. Estos métodos son equiparables a las operaciones CRUD (Create, Read, Update, Delete) de las bases de datos. Aclarado esto, empecemos con las recomendaciones.

 

Usar nombres pero no verbos


Por cuestiones de mejor comprensión y legibilidad de la semántica de la API, usa sólo nombres para toda su estructura.

Recurso POST
create
GET
read
PUT
update
DELETE
/cars Crea un nuevo coche Devuelve la lista de coches Actualización en bloque de coches Borrar todos los coches
/cars/711 Método no permitido (405) Devuelve un coche específico Actualiza un coche específico Borra un coche específico

No usar verbos como:

/getAllCars
/createNewCar
/deleteAllRedCars

La propia semántica que compone la URL, junto con el método  HTTP usado (POST, GET, PUT, DELETE), permite prescindir de verbos como “create”, “get”, “update” y “delete”.

 

Métodos GET y los parámetros de consulta no deben alterar el estado


Usa los métodos POST, PUT o DELETE para cambiar los estados de los recursos, en vez de hacerlo con el método GET o un petición con parámetros de consulta. Para algo tienes 3 métodos que te permiten hacer eso 😉 .

Esto es lo que no se debería hacer:

GET /users/711?activate
GET /users/711/activate

Es mucho mejor hacer esto:

PUT /users/711/activate

o esto:

POST /users/711/activate

Cuál usar dependerá del diseño de la base de datos o la lógica con la que se estructura el almacenamiento de la misma.

 

Usar nombres en plural


No mezcles nombres en singular con nombres en plural. Hazlo simple y mantén los nombres en plural.

En vez de usar:

/car
/user
/product
/setting

Usa el plural:

/cars 
/users 
/products 
/settings

El uso del plural te permitirá posteriormente hacer operaciones del tipo:

/cars/<id> 
/users/<id> 
/products/<id> 
/settings/<name>

 

Usar subrecursos para establecer relaciones


Si un recurso está relacionado con otro, usa subrecursos montados sobre la estructura de la URL.

GET /cars/711/drivers/ Devuelve una lista de conductores para el coche 711
GET /cars/711/drivers/4 Devuelve el conductor #4 para el coche 711

 

Usar cabeceras HTTP para la serialización de formatos


Tanto la parte cliente como la del servidor, necesitan saber en qué formato se están pasando los datos para poder comunicarse. Lo más sencillo es especificarlo en la cebecera HTTP.

Content-Type: Define el formato de la petición.
Accept: Define la lista de formatos aceptados en la respuesta.

 

Usar HATEOAS


El uso de HATEOAS (Hypermedia as the Engine of Application State) es un diseño que nos permite incluir el principio de hipervínculos de manera similar a la navegación web, lo que nos permite una mejor navegación por la API.

En este ejemplo la respuesta en formato JSON nos devuelve junto con la información del equipo con id 5000, una serie de referencias a recursos relacionados, como pueden ser el estadio del equipo o sus jugadores. Normalmente se suele agrupar todas las referencias dentro de una propiedad o atributo llamada “links“.

{
    "links": [{
        "rel": "self",
        "href": "http://localhost:8080/soccer/api/teams/5000"
    }, {
        "rel": "stadium",
        "href": "http://localhost:8080/soccer/api/teams/5000/stadium"
    }, {
        "rel": "players",
        "href": "http://localhost:8080/soccer/api/teams/5000/players"
    }],
    "teamId": 5000,
    "name": "Real Madrid C.F.",
    "foundationYear": 1902,
    "rankingPosition": 1
}

Este tipo de diseño está pensado para la longevidad del software y la evolución independiente, ya que frecuentemente en la arquitectura de sistemas y servicios, es a corto plazo lo que más suele fallar.

 

Proveer filtrado, ordenación, selección de campos y paginación para colecciones


 

Filtrado

Utilizar un parámetro de consulta único para todos los campos o un lenguaje de consulta formalizado para filtrar.

GET /cars?color=red Devulve una lista de coches rojos
GET /cars?seats<=2 Devuelve una lista de coches con un máximo de 2 plazas

 

Ordenación

Permitir ordenación ascendente o descendente sobre varios campos

GET /cars?sort=-manufactorer,+model

En el ejemplo se devuelve una lista de coches ordenada con los fabricantes de manera descendiente y los modelos de manera ascendente.

 

Selección de campos

Permitir la selección de unos pocos campos de un recurso si no se precisan todos. Dar al consumidor de la API la posibilidad de qué campos quiere que se devuelvan, reduce el volumen de tráfico en la comunicación y aumenta la velocidad de uso de la API.

GET /cars?fields=manufacturer,model,color

En el ejemplo se pide la lista de coches, pero pidiendo sólo los campos de “fabricante“, “modelo” y “color“.

 

Paginación

Uso de “offset” para establecer la posición de partida de una colección y “limit” para establecer el número de elementos de la colección a devolver desde el offset. Es un sistema flexible para el que consume la API y bastante extendido entre los sistemas de bases de datos.

GET /cars?offset=10&limit=5

En el ejemplo se devuelve una lista de coches correspondiente a los coches comprendidos de la posición 10 a la 15 de la colección.

Para devolver al consumidor de la API el número total de entradas se puede usar la cabecera HTTP  “X-Total-Count” y para completar la información proporciona, por ejemplo, devolver los enlaces a la página previa y siguiente, entre otros, usando la cabecera HTTP “Link“.

Link: <http://localhost/sample/api/v1/cars?offset=15&limit=5>; rel="next",
<http://localhost/sample/api/v1/cars?offset=5&limit=5>; rel="prev",
<http://localhost/sample/api/v1/cars?offset=50&limit=3>; rel="last",
<http://localhost/sample/api/v1/cars?offset=0&limit=5>; rel="first",

Como alternativa es posible usar HATEOAS, como ya he comentado anteriormente.

 

Versionar la API


Es muy recomendable, tirando a obligatorio 😉 , el poner versión de API y no liberar APIs sin versión. Usa un simple número para especificar la versión y no uses un versionado tipo semver del tipo 1.5.

Si se usa la URL para marcar la versión, pon una “v” precediendo el número de versión.

/blog/api/v1

Es la forma más sencilla y eficaz de asegurar la compatibilidad en el versionado de la API. Especificarla como parámetro o en la petición y/o en la respuesta, conlleva el aumento del tráfico y el  coste de  computación, al tener que existir lógica para discriminar las distintas versiones soportadas sobre una misma URL.

 

Manejar errores con código de estado HTTP


Es difícil trabajar con una API que ignora el manejo de errores, por no decir imposible 😉 . La devolución de un código HTTP 500 para cualquier tipo de error o acompañado de una traza de error del código del servidor no es muy útil, además de que puede ponernos en peligro ante una vulnerabilidad que un atacante quisiera explotar.

 

Usar códigos de estado HTTP

El estándar HTTP proporciona más de 70 códigos de estado para describir los valores de retorno. En general no los utilizaremos todos, pero se debe utilizar por lo menos un mñinimo de 10, que suelen ser los más comunes:

Código Significado Explicación
 200  OK  Todo está funcionado
 201  OK  Nuevo recurso ha sido creado
 204  OK  El recurso ha sido borrado satisfactoriamente
 304  No modificado  El cliente puede usar los datos cacheados
 400  Bad Request  La petición es inválida o no puede ser servida. El error exacto debería ser explicado en el payload de respuesta
 401  Unauthorized  La petición requiere de la autenticación del usuario
 403  Forbidden  El servidor entiende la petición pero la rechaza o el acceso no está permitido
 404  Not found  No hay un recurso tras la URI
 422  Unprocessable Entity  Debe utilizarse si el servidor no puede procesar la entidad. Por ejemplo, faltan campos obligatorios en el payload.
 500  Internal Server Error  Los desarrolladores de APIs deben evitar este error. Si se produce un error global, el stracktrace se debe registrar y no devolverlo como respuesta.

 

Usar el payload para los errores

Todas las excepciones deben ser asignadas en un payload de error. A continuación se muestra un ejemplo de cómo podría verse un payload de error en formato JSON:

{
  "errors": [
   {
    "userMessage": "Sorry, the requested resource does not exist",
    "internalMessage": "No car found in the database",
    "code": 34,
    "more info": "http://dev.mascandobits.es/blog/api/v1/errors/12345"
   }
  ]
}

 

Permitir la sustitución del método HTTP


Algunos proxys sólo admiten métodos POST y GET. Para que una API RESTful funcione con estas limitaciones, la API necesita una forma de sustituir el método HTTP.

Una opción es utilizar la cebecera HTTP “X-HTTP-Method-Override” para sobrescribir el método POST y así personalizar la petición POST para que cumpla, por ejemplo, una operación DELETE.

X-HTTP-Method-Override: DELETE

 

Espero que esta concisa guía os permita realizar APIs RESTful con un mejor diseño, o mejorar aquellas que ya tengáis desarrolladas, eso sí generando una nueva versión de la API 😉 .