Notas sobre diseño de APIs

Después de releer el libro de Phil Sturgeon Build APIs you won’t hate dejo aquí estas notas a tener en cuenta para el diseño de APIs:

  • No usar un número autoincremental como identificador de los recursos, es mejor utilizar un identificador alfanumérico.
  • Nombres de los recursos en plural (places, users, etc.)
  • Los nombres de los recursos no deben ser verbos sino sustantivos. Por ejemplo, en vez de /users/5/send-message es mejor /users/5/messages
  • Para generar documentación: Api Blueprint
  • Principales códigos de respuesta:
    • 200 – Generic everything is OK
    • 201 – Created something OK
    • 202- Accepted but is being processed async (like video encodings)
    • 204 – The server has successfully fulfilled the request and that there is no additional content to send in the response payload body
    • 400 – Bad Request (should really be for invalid syntax but some folks use it for validation)
    • 401 – Unauthorized (no current user and there should be)
    • 403 – The current user is forbidden from accessing this data
    • 404 – That URL is not a valid route, or the item resource does not exist
    • 410 – Data has been deleted, deactivated, suspended, etc
    • 405 – Method Not Allowed (your framework will probably do this for you)
    • 500 – Something unexpected happened and it is the APIs fault
    • 503 – API is not here right now, please try again later
  • Ejemplo de paginado:
{
  "data": […],
  "pagination" :
  {
    "total": 1000,
    "count": 12,
    "per_page": 12,
    "current_page": 1,
    "total_pages": 84,
    "next_url": "/places?page=2&number=12",
  }
}

Enviar enlaces ed2k a mldonkey (configurar xdg-open para el protocolo ed2k)

Es habitual tener un ordenador pequeño tipo Raspberry Pi o similar encendido continuamente como servidor de archivos, y seguramente tengamos corriendo en él mldonkey, que es un cliente tipo eMule de línea de comandos.

Si queremos que los enlaces ed2k de las páginas que visitemos se añadan como descargas podemos usar una extensión como esta, que envía los enlaces a nuestro servidor mldonkey.

Pero claro, lo más normal hoy día es que la página que visitemos esté bajo https, y nuestro servidor mldonkey esté bajo http, lo que hace que el navegador rechace abrir una URL no segura desde un sitio seguro.

Para solucionar este problema vamos a hacer otra cosa. Nos olvidaremos de la extensión del navegador y registraremos un manejador para el protocolo ed2k://. Este manejador abrirá los enlaces en una aplicación que vamos a crear que hará la conexión con el servidor mldonkey.

Dicho así parece mucho más complicado de lo que es, ya verás. Lo primero que haremos será crear un fichero ~/.local/share/applications/ed2k.desktop con este contenido:

[Desktop Entry]
Version=1.0
Type=Application
Terminal=true
Name=ED2K Link Handler
Comment=Sends ed2k links to remote mldonkey server
Exec=ed2kHandler %u
MimeType=x-scheme-handler/ed2k

Las dos líneas más importantes son las dos últimas, donde indicamos el programa al que se enviarán los enlaces y el tipo mime que queremos registrar. ed2kHandler es el nombre de nuestra pequeña aplicación y en el tipo mime la parte ed2k del final es lo que indica que queremos asociarla a las URLs que usen el protocolo ed2k.

Una vez hecho esto ejecutamos estas dos líneas:

sudo update-desktop-database
xdg-mime default ed2k.desktop x-scheme-handler/ed2k

y ya tendremos hecha la asociación del protocolo con nuestra aplicación. Ya solo nos faltaría crear la aplicación.

La aplicación la haremos con PHP, y para ello crearemos el fichero /usr/bin/ed2kHandler con este contenido (una vez creado hay que darle permisos de ejecución):

!/usr/bin/php
<?php

if (!isset($argv[1]))
    die("Usage: ed2kHandler elink\n");

$url = 'http://USER:PASS@192.168.0.4:4080/submit?q=';
$url .= $argv[1];
$url = str_replace('ed2k://', 'ed2k%3A%2F%2F', $url);

file_get_contents($url);

Mover carpeta de datos de MySQL

Hay ya miles de entradas sobre cómo cambiar la carpeta de datos de MySQL de /var/lib/mysql a cualquier otra, pero me costó encontrar la solución al problema “Error 13 – Permission denied” que me daba al intentar arrancar MySQL después de cambiarle la carpeta de datos.

El problema es que la nueva ruta estaba en /media/koas/Ext4Bucket, un segundo disco duro que tengo instalado. Para que funcione hay que darle a /media/koas permisos 777.

Nuevo artículo en dev.to

En este blog escribo básicamente para mí mismo, pero hay algunos temas sobre los que creo que puedo escribir artículos que realmente sean útiles para más personas. Esos artículos los escribiré (en inglés) en dev.to, que es un portal de contenido para desarrolladores.

Y aquí tenemos el primero, habla sobre cómo usar cabeceras HTTP para ayudarnos a depurar sitios web que están en producción.

Música para programar: el género Italo Disco y las sesiones de Juan Prada

Hace unos años en un viaje a Cangas de Onís para actuar con la Orquesta Vaya Panorama mi amigo Juan Prada me descubrió el género Italo Disco, que es básicamente música disco italiana de los ochenta que está muy bien para programar.

Fue una recomendación doble, porque Juan además de programador también es DJ, así que sabe mucho de los dos mundos. Podéis descargar las sesiones que hace para Frisky Radio (que también son ideales para programar) en su página web.

Cambiar el lenguaje de programación de un repositorio de GitHub

A veces GitHub no detecta correctamente el lenguaje principal de un repositorio. Por ejemplo, para Mi Segundo PC como tiene más ficheros con extensión php que js decía que el lenguaje era PHP en vez de JS.

Para solucionarlo creamos un fichero .gitattributes en el directorio raíz del repositorio con este contenido:

* linguist-vendored
*.js linguist-vendored=false

Esto le indica a GitHub que desactive la detección de lenguaje para todos los ficheros y la active para los .js, haciendo así que el lenguaje detectado sea JavaScript.

Eliminando autenticación para phpMyAdmin

¡Atención! Esto solo hay que hacerlo en nuestro equipo de desarrollo, lógicamente es una locura quitar la autenticación al phpMyAdmin en un servidor accesible desde Internet, ahí no solo debemos tener autenticación sino proteger además la carpeta con una contraseña de acceso porque phpMyAdmin no tiene ninguna protección contra ataques de fuerza bruta (no entiendo por qué, no les costaría nada implementar algo como phpLoginBlacklist).

Pero en nuestro equipo es un rollo que cada cierto tiempo caduque la sesión y nos pida que nos identifiquemos otra vez, así que la solución es editar el fichero /etc/phpmyadmin/config.inc.php y en el bloque de datos del primer servidor añadir estas líneas:

// Esta línea ya existirá, cambiamos su valor a config
$cfg['Servers'][$i]['auth_type'] = 'config';

// Estas son las líneas que añadiremos
$cfg['Servers'][$i]['user'] = 'root';
$cfg['Servers'][$i]['password'] = 'pass';
$cfg['Servers'][$i]['AllowNoPassword'] = TRUE;
$cfg['Servers'][$i]['AllowRoot'] = TRUE;

Sublime Text: convertir espacios a tabs al guardar un fichero

No soy un maniático como Richard en Silicon Valley:

Aunque yo también prefiero usar tabulados

pero como llevo un tiempo usando Pug para el HTML en Vue he acabado harto del mensaje de error Invalid indentation, you can use tabs or spaces but not both.

Para solucionar esto crearemos una carpeta UnexpandTabsOnSave en la carpeta Packages de la configuración de Sublime Text y dentro un fichero UnexpandTabsOnSave.py con este contenido:

import sublime, sublime_plugin, os

class UnexpandTabsOnSave( sublime_plugin.EventListener ):
  # Run Sublime's 'unexpand_tabs' command when saving any file
  def on_pre_save( self, view ):
    view.window().run_command( 'unexpand_tabs' )

Así cada vez que guardemos un fichero convertirá los espacios a tabs, Pug no se quejará y el Richard que llevamos dentro estará satisfecho.

Detectar atajos de teclado en una aplicación Vue

Para asociar atajos de teclado globales lo más sencillo es establecerlos en el div principal de nuestra aplicación Vue.

Así que si queremos por ejemplo lanzar nuestro menú de aplicaciones cuando el usuario haga Ctrl + Clic en cualquier parte de la página o pulse la combinación de teclas Meta + Espacio usaríamos este código:

<div id="app"
     v-on:keyup.meta.space="launchAppsMenu"
     v-on:click.ctrl="launchAppsMenu"></div>

Sin embargo al probar esto veríamos que el Ctrl + Clic funciona pero no así el Meta + Espacio. Esto es porque los eventos de teclado solo se generan para elementos que pueden tener el foco (focusables) y los div no son por defecto focusables. Para que lo sean solamente tenemos que añadirle el atributo tabindex, una vez lo tenga podrá recibir eventos de teclado. Así quedaría entonces nuestro código:

<div id="app" tabindex="0" 
     v-on:keyup.meta.space="launchAppsMenu"
     v-on:click.ctrl="launchAppsMenu"></div>

Número de compilación automático en aplicaciones Vue

Para disponer del número de compilación en nuestra aplicación Vue he creado este pequeño script. Para usarlo hay que modificar el fichero package.json y sustituir en “scripts” el valor de “build” por ./buildAndUpload.php

Luego creamos el fichero ./buildAndUpload.php con este contenido:

#!/usr/bin/php
<?php
// Get version number
$version = json_decode(file_get_contents('package.json'), true)['version'];
$version = substr($version, 0, -2);

// Get build number
$build = trim(file_get_contents('.buildNumber')) + 1;
file_put_contents('.buildNumber', $build);

echo "Shipping version $version build $build\n\n";

// Save version file
$js = "var appVersion = $version;var buildNumber = $build;";
file_put_contents('./public/appVersion.js', $js);

exec('vue-cli-service build');

// Upload dist folder to server

El número de compilación inicial lo guardaremos en el fichero .buildNumber. Y con esto ya estaría todo, ahora cada vez que compilemos nuestra aplicación se generará en la carpeta dist un fichero appVersion.js que podremos incluir en nuestra aplicación y que contendrá el número de versión (que se extrae del fichero package.json) y el número de compilación.