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);

Reglas generales para el género de los sustantivos en alemán

Una de las partes complicadas del alemán es saber el género de los sustantivos, porque hay tres y no coinciden con los que usamos en español, así que me copio aquí unas cuantas reglas generales para tenerlas a mano y repasarlas de vez en cuando. Ojo que todas tienen excepciones, pero para salir del paso si no recordamos el género pueden servir:

Masculino

  • Sexo natural según el género: der Vater, der Sohn, der Onkel.
  • Profesiones: der Polizist, der Koch, der Lehrer. Para construir el femenino añadimos -in: die Polizistin, die Köchin, die Lehrerin.
  • En general los países no tienen género, pero los que lo tienen son masculinos: der Libanon, der Irak, der Iran, der Sudan, der Jemen.
  • Las estaciones del año (der Frühling, der Sommer, der Herbst, der Winter), los meses del año y los días de la semana.
  • Precipitaciones, tormentas, rayos y centellas: der Regen, der Schnee, der Sturm, der Donner, der Blitz,…
  • Los puntos cardinales: der Norden, der Süden, der Osten, der Westen.
  • Marcas de coches: der Audi, der BMW
  • Montañas, minerales y piedras
  • Nombres de bebidas alcohólicas (ojo, no das Bier claro)
  • Terminaciones de palabras típicas de masculino:
    • -and
    • -ant
    • -är
    • -ast
    • -ent
    • -er
    • -eur
    • -ich
    • -ig
    • -iker
    • -ismus
    • -ist
    • -ling
    • -or

Femenino

  • Sexo natural según el género: die Mutter, die Tante, die Tochter
  • Las especies de árboles: aunque el árbol es masculino (der Baum), las especies de árboles son femeninas: die Ulme, die Eiche
  • Las flores, los números, aviones, motos y barcos.
  • Terminaciones de palabras típicas de femenino:
    • -ade
    • -age
    • -aille
    • -aise
    • -anz
    • -e
    • -ei
    • -elle
    • -enz
    • -ette
    • -ie
    • -ik
    • -ille
    • -ine
    • -in
    • -ion
    • -isse
    • -ität
    • -itis
    • -ive
    • -heit
    • -keit
    • -schaft
    • -sis
    • -ung
    • -ur

Neutro

  • Metales
  • Elementos químicos
  • Hoteles, cines y cafés
  • Colores
  • Notas musicales
  • Unidades físicas
  • Letras del abecedario
  • Terminaciones de palabras típicas del neutro
    • -chen: todos los diminutivos son neutros.
    • -ett
    • -ing
    • -ma
    • -tel
    • -um

Fuentes: Crónicas germánicas, alemanista.com