Modelos de URI (RFC 6570): expandir nos quatro níveis

O que é um modelo de URI?

Um modelo de URI é uma URL com buracos. Um nome entre chaves no meio de um caminho é um buraco; e uma lista entre chaves no fim, começando por um ponto de interrogação, também é, e vira uma string de consulta. Dê a ele um conjunto de valores e ele vira uma URL de verdade. O formato é a RFC 6570, e ele faz bem mais do que substituir texto: sabe distinguir um segmento de caminho de um parâmetro de consulta, escapa cada um pelas regras certas e consegue transformar uma lista em vários parâmetros repetidos.

Você quase certamente já recebeu um sem que ninguém avisasse. Peça qualquer coisa à API do GitHub e a resposta vem cheia deles: só o documento raiz devolve campos terminados num id de gist entre chaves e num par de parâmetros de paginação também entre chaves. É essa a ideia do formato: o servidor descreve uma vez o formato de um espaço de URLs e o cliente preenche as lacunas, em vez de cada cliente concatenar texto na mão e errar o escape.

São quatro níveis. O primeiro é substituição simples. O segundo acrescenta as duas expansões que deixam barras e outros caracteres reservados passarem intactos. O terceiro acrescenta os operadores de caminho, consulta e fragmento, e permite nomear várias variáveis numa mesma expressão. O quarto acrescenta os dois modificadores de valor: pegar os primeiros caracteres, ou desdobrar uma lista em parâmetros repetidos. Um modelo real do GitHub para no nível 3, e vale saber disso, porque o nível 4 é justamente onde as implementações começam a divergir.

Como usar

1. Cole um modelo. Tudo entre chaves é uma expressão; o resto é copiado como está, com os caracteres que uma URL não aguenta codificados no caminho. Os botões de exemplo cobrem um modelo real de API, um parâmetro repetido, a expansão reservada e um prefixo.
2. Informe alguns valores em JSON. Uma string é um valor simples, um array é uma lista e um objeto é um conjunto de pares de nome e valor. Deixar um nome de fora não é erro: uma variável indefinida não produz nada, que é exatamente como funcionam os parâmetros opcionais.
3. Leia o detalhamento. Abaixo do resultado há uma linha para cada pedaço do modelo com o pedaço de URL que ele produziu. É ali que as regras de escape ficam visíveis, e onde um erro aparece como uma linha que contribuiu com ela mesma, sem alteração.

Um modelo quebrado também devolve uma URL

Escreva um modelo com um erro e esta ferramenta não vai parar. Ela expande tudo o que der, copia o trecho quebrado exatamente como você escreveu e diz embaixo o que está errado. Isso não é leniência, é a especificação: quando um processador encontra uma expressão ruim, a parte não processada deve ser copiada ao resultado sem expandir, o processamento deve continuar e quem chamou deve ser informado do local e do tipo do erro. A RFC descreve o resultado como algo destinado apenas a diagnóstico.

Há um motivo para um formato de hipermídia ser escrito assim. Os modelos que você expande costumam chegar de outro lugar, dentro da resposta de uma API que não foi você que escreveu, e um cliente que estoura diante de um campo inesperado é pior do que um que segue em frente e relata o problema. Os dois modos de falha são até deliberadamente diferentes: um caractere indevido fora de uma expressão para a leitura na hora, então tudo que vem depois, inclusive expressões que teriam funcionado, fica exatamente como estava. Experimente o exemplo com erro e repare em quais partes ainda expandem.

O problema é que quase ninguém implementa a parte de relatar. Enquanto esta página era construída, dois expansores publicados foram medidos: diante dos trinta e seis modelos que a própria suíte de testes do formato marca como inválidos, nenhum lançou erro e nenhum devolveu qualquer indicação de que algo estivesse errado. Os dois devolveram uma URL de aparência plausível em todos os casos, e em cinco dos trinta e seis devolveram URLs diferentes entre si. Se você já se perguntou por que um modelo malformado virou uma requisição errada em vez de um erro visível, é por isso.

Uma especificação sem proibições

A RFC 6570 não contém nenhum MUST NOT nem nenhum SHOULD NOT — nenhum, fora o parágrafo de praxe que explica o que essas palavras significam. No documento inteiro há quatro MUST, sete SHOULD e três MAY. Isso é incomum, e explica o resto: quando o tratamento de erros é escrito como SHOULD, uma implementação é conforme seguindo ou não, e em geral não segue.

Há também um ponto em que ela se contradiz, e aqui a ferramenta segue a suíte de testes e não a gramática. A regra sobre o que pode aparecer fora de uma expressão exclui o apóstrofo e o cita nominalmente entre os caracteres proibidos. Só que apóstrofo é legal numa URL, a seção logo acima diz que caracteres legais numa URL são copiados como estão, e a suíte oficial de conformidade traz um caso exigindo que o apóstrofo sobreviva, arquivado sob o número da mesma seção cuja gramática o proíbe. Aqui a suíte ganha.

Mais uma regra que vale conhecer porque é invisível no modelo. Pedir os primeiros caracteres de um valor conta caracteres, não as unidades em que uma linguagem de programação por acaso os guarda. A especificação diz isso duas vezes e dá o motivo: é para impedir que uma implementação corte um caractere ao meio. Peça às duas bibliotecas medidas o primeiro caractere de um sinal musical de clave e nenhuma devolve: as duas lançam erro, porque cortar uma string de JavaScript na posição um parte esse caractere em duas metades e deixa um fragmento inválido.

O que esta ferramenta não faz

Ela não vai no sentido inverso. Extrair os valores de uma URL já pronta, ou seja casar em vez de expandir, é um problema bem mais difícil, e a RFC também se esquiva dele com as próprias palavras: o casamento, diz ela, só funciona bem quando as expressões estão delimitadas pelas pontas da URL ou por caracteres que não podem aparecer na expansão, e em geral expressões regulares servem melhor para essa tarefa. Um modelo que termina em duas variáveis grudadas, sem nada entre elas, não tem uma única resposta certa.

Ela não busca nada nem verifica se a URL que produz existe. Um modelo que expande para um endereço perfeitamente formado de um recurso que ninguém nunca criou parece igualzinho a um que funciona. E vale lembrar na outra direção também, nas palavras da especificação: um modelo não é um URI. Ele não identifica um recurso, não é analisado como tal e não deveria ser colocado onde se espera um URI antes que algo o tenha expandido — que é justamente por que uma API que serve modelos dá a eles nomes de campo próprios em vez de misturá-los com os links prontos.

Os resultados daqui são conferidos contra a suíte de conformidade da própria especificação, e não contra outra biblioteca: os 117 casos positivos, e os 36 modelos inválidos apontados como inválidos em vez de expandidos em silêncio. Concordar com outra implementação só mostraria que duas pessoas fizeram as mesmas escolhas.

Por que é grátis?

Expandir um modelo é manipulação de texto, e acontece no seu navegador. Não há servidor no meio, então não há o que cobrar nem conta a criar.

Nada é enviado. O modelo que você cola e os valores que digita ficam nesta aba.