Category: Programación

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

posted by under Programación ,

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

posted by under Programación , , ,

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

posted by under Programación

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

RecursoPOST
create		GET
read		PUT
update		DELETE
/carsCrea un nuevo cocheDevuelve la lista de cochesActualización en bloque de cochesBorrar todos los coches
/cars/711Método no permitido (405)Devuelve un coche específicoActualiza un coche específicoBorra un coche específico

No usar verbos como:

/getAllCars
/createNewCar
/deleteAllRedCar

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ódigoSignificadoExplicació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 😉 .

 

Clonar la Wiki de un proyecto «forkeado» en GitHub

posted by under Programación

GitHub es una plataforma increíble que hace todo más fácil en la gestión de proyectos versionados con Git. Una de las grandes cosas que tiene GitHub es la de hacer un fork, que es una copia vinculada al repositorio original bajo tu completa administración.

Esta copia no es completa, puesto que no incluye algunas cosas relevantes como la Wiki, que es donde se documenta la información del proyecto. A efectos prácticos la Wiki se comporta exactamente igual que un repositorio gestionado con Git y que se compuesto por ficheros markdown. A mi juicio, el hacer un fork del proyecto debería incluir tanto el repositorio principal del proyecto como el repositorio Wiki del mismo. Quizás en un futuro no muy lejano lo veamos, quién sabe... 😉

Cuando hacemos un fork de un proyecto y vamos a la Wiki nos anima a crear nuestra primera página:

Aunque pudiera parece que al haber una sección Wiki, existe un repositorio, esto no es así. Hasta que no creemos la primera página que suele denominarse "Home", el repositorio de la Wiki no existirá. Si se intenta hacer push al repositorio, seguramente os arroje un error como este:

remote error: access denied or repository not exported

Esto es un error de falta de permisos que puede hacerte perder bastante el tiempo, si no caes en la cuenta que el error no es por falta de permisos, sino por la ausencia de repositorio.

Una vez aclarado el tema basta con darle a "Create the first page":

Dejaremos tal cual está todo porque sobrescribiremos el contenido, sólo lo hacemos para que se cree el repositorio de la Wiki. Avanzamos hacia abajo y le damos a "Save Page".

Ahora tenemos nuestra Wiki inicializada con su reapositorio activo:

Una vez llegados a este punto hay dos formas de hacer las cosas. En la primera de ellas, puede que la más fácil, sea hacer un clone del repositorio Wiki del original, hacer otro clone de nuestro repositorio Wiki en el fork, y copiar todos los archivos del repositorio Wiki original al de nuestro fork. De esta forma al hacer commit y luego push en nuestro repositorio, tendremos la Wiki. El mayor problema de este método es que primero vamos a tener un commit inicial y que luego vamos a tener un segundo con toda la Wiki. Esto nos hace perder el versionado que traía consigo el repositorio Wiki del proyecto original.

Otra forma más óptima que nos permite mantener el versionado del repositorio Wiki del proyecto original, es el que paso a describiros a continuación de manera detallada.

Primero hacemos un "git clone" del repositorio Wiki del proyecto original:

git clone url_wiki_original

Una vez clonado añadimos nuestra Wiki del fork como remoto con "git remote" (no usar como "remote_name" el nombre de origin):

git remote add remote_name url_wiki_fork

Ahora con el nuevo remoto añadido podemos hacer un "git push" forzado:

git push remote_name master --force

El parámetro "remote_name" es el mismo que cuando hemos añadido el remote en el paso anterior (el de la Wiki de nuestro fork), la rama es "master" (rama principal pero que puede ser cualquier otra que se quiera), y el parámetro "--force" que sirve para sobrescribir la referencia que tuviese anteriormente de la rama y sobrescribir por la que se manda (cuidado con este parámetro que puede resultar peligroso).

El resultado como podéis ver es la de nuestra Wiki actualizada con la del proyecto original:

Ahora queda un minúsculo detalle y es el "HEAD", la referencia que indica cual es remote y rama por defecto. Por defecto apunta a "origin/master", que es el remoto de donde se hace el clone. Por esta razón hay que cambiar el "HEAD" para que apunte a nuestro fork como origin y a nuestra rama master. La manera más sencilla es coger y hacernos un "git clone" del repositorio Wiki de nuestro fork y todo listo. 😉

Con este procedimiento ya podéis incluir en vuestros forks la tan preciada y a veces escasa documentación  que se adjunta en los repositorios de los proyectos.