Plantillas URI (RFC 6570): expandir con los cuatro niveles

¿Qué es una plantilla URI?

Una plantilla URI es una URL con huecos. Un nombre entre llaves en mitad de una ruta es un hueco; también lo es una lista entre llaves al final que empieza por un signo de interrogación y se convierte en una cadena de consulta. Le das un conjunto de valores y se convierte en una URL de verdad. El formato es el RFC 6570 y da bastante más de sí que una sustitución de cadenas: distingue un segmento de ruta de un parámetro de consulta, escapa cada cosa con las reglas que le tocan y sabe convertir una lista en varios parámetros repetidos.

Es casi seguro que has recibido alguna sin que nadie te lo dijera. Pide cualquier cosa a la API de GitHub y la respuesta viene llena: solo el documento raíz devuelve campos que terminan en un identificador de gist entre llaves y en un par de parámetros de paginación también entre llaves. Esa es la gracia del formato: el servidor describe una vez la forma de un espacio de URLs y el cliente rellena los huecos, en lugar de que cada cliente concatene cadenas a mano y se equivoque con el escapado.

Hay cuatro niveles. El primero es sustitución llana. El segundo añade las dos expansiones que dejan pasar barras y otros caracteres reservados sin tocarlos. El tercero añade los operadores de ruta, consulta y fragmento, y permite nombrar varias variables en una misma expresión. El cuarto añade los dos modificadores de valor: quedarse con los primeros caracteres, o desplegar una lista en parámetros repetidos. Una plantilla real de GitHub se queda en el nivel 3, y conviene saberlo, porque el nivel 4 es justo donde las implementaciones empiezan a discrepar.

Cómo usarlo

1. Pega una plantilla. Todo lo que va entre llaves es una expresión; el resto se copia tal cual, codificando por el camino los caracteres que una URL no puede llevar. Los botones de ejemplo cubren una plantilla real de una API, un parámetro repetido, la expansión reservada y un prefijo.
2. Dale unos valores en JSON. Una cadena es un valor suelto, un array es una lista y un objeto es un conjunto de pares de nombre y valor. Dejarse un nombre fuera no es un error: una variable indefinida no produce nada, que es justo como funcionan los parámetros opcionales.
3. Lee el desglose. Bajo el resultado hay una fila por cada trozo de la plantilla con el trozo de URL que ha producido. Ahí es donde se ven las reglas de escapado, y donde un fallo aparece como una fila que se ha aportado a sí misma, sin cambios.

Una plantilla rota también te da una URL

Escribe una plantilla con un fallo y esta herramienta no se detendrá. Expandirá todo lo que pueda, copiará el trozo roto exactamente como lo has escrito y te dirá debajo qué falla. No es tolerancia, es la especificación: cuando un procesador se topa con una expresión mala, la parte sin procesar debe copiarse al resultado sin expandir, el procesado debe continuar y hay que informar a quien llama de dónde y de qué tipo es el error. El RFC describe el resultado como algo pensado solo para diagnóstico.

Que un formato de hipermedia esté escrito así tiene su motivo. Las plantillas que expandes suelen llegarte de otro sitio, dentro de la respuesta de una API que no has escrito tú, y un cliente que revienta ante un campo inesperado es peor que uno que sigue adelante e informa. Los dos modos de fallo son además distintos a propósito: un carácter indebido fuera de una expresión detiene el análisis en seco, así que todo lo que viene detrás, incluidas expresiones que habrían funcionado, se queda tal cual. Prueba el ejemplo del fallo y fíjate en qué partes se siguen expandiendo.

El problema es que casi nadie implementa la parte de informar. Mientras se construía esta página se midieron dos expansores publicados: ante las treinta y seis plantillas que la propia suite de pruebas del formato marca como inválidas, ninguno lanzó un error y ninguno devolvió indicación alguna de que algo fuera mal. Los dos devolvieron una URL de aspecto razonable en todos los casos, y en cinco de las treinta y seis devolvieron URLs distintas entre sí. Si alguna vez te has preguntado por qué una plantilla mal formada acabó en una petición equivocada en lugar de en una traza de error, ahí lo tienes.

Una especificación sin prohibiciones

El RFC 6570 no contiene ningún MUST NOT ni ningún SHOULD NOT: ni uno, fuera del párrafo de rigor que explica qué significan esas palabras. En todo el documento hay cuatro MUST, siete SHOULD y tres MAY. Es raro, y explica lo demás: si el tratamiento de errores está escrito como SHOULD, una implementación es conforme lo siga o no, y en general no lo sigue.

También hay un punto en el que se contradice, y aquí la herramienta hace caso a la suite de pruebas y no a la gramática. La regla sobre qué puede aparecer fuera de una expresión excluye el apóstrofo y lo nombra expresamente entre los caracteres prohibidos. Pero un apóstrofo es legal en una URL, la sección de justo encima dice que los caracteres legales en una URL se copian tal cual, y la suite oficial de conformidad incluye un caso que exige que el apóstrofo sobreviva, archivado bajo el número de la misma sección cuya gramática lo prohíbe. Aquí gana la suite.

Una regla más que conviene conocer porque no se ve en la plantilla. Pedir los primeros caracteres de un valor cuenta caracteres, no las unidades en las que un lenguaje de programación los guarde. La especificación lo dice dos veces y da el motivo: está ahí para que ninguna implementación parta un carácter por la mitad. Pídeles a las dos bibliotecas medidas el primer carácter de un signo musical de clave y ninguna te lo devuelve: las dos lanzan un error, porque cortar una cadena de JavaScript en la posición uno parte ese carácter en dos mitades y deja un fragmento inválido.

Lo que esta herramienta no hace

No va en sentido contrario. Sacar los valores de una URL ya formada, es decir emparejar en vez de expandir, es un problema bastante más difícil, y el RFC también lo esquiva con sus propias palabras: el emparejamiento, dice, solo funciona bien cuando las expresiones están delimitadas por los extremos de la URL o por caracteres que no pueden aparecer en la expansión, y en general las expresiones regulares se prestan mejor a esa tarea. Una plantilla que acaba en dos variables pegadas sin nada en medio no tiene una única respuesta correcta.

No descarga nada ni comprueba que la URL que produce exista. Una plantilla que se expande a una dirección perfectamente formada de un recurso que nadie creó nunca se ve igual que una que funciona. Y conviene recordarlo también en la otra dirección, en palabras de la especificación: una plantilla no es un URI. No identifica ningún recurso, no se analiza como tal y no debería ponerse donde se espera un URI hasta que algo la haya expandido, que es justamente por lo que una API que sirve plantillas les da nombres de campo propios en vez de mezclarlas con los enlaces ya terminados.

Los resultados de aquí se comprueban contra la suite de conformidad de la propia especificación y no contra otra biblioteca: los 117 casos positivos, y las 36 plantillas inválidas señaladas como inválidas en lugar de expandidas en silencio. Coincidir con otra implementación solo demostraría que dos personas tomaron las mismas decisiones.

¿Por qué es gratis?

Expandir una plantilla es manipular cadenas, y ocurre en tu navegador. No hay servidor de por medio, así que no hay nada que facturar ni cuenta que crear.

No se sube nada. La plantilla que pegas y los valores que escribes se quedan en esta pestaña.