T
rfc6570 uri-template api-design rest web-standards

Templates de URI Explicados: Domine a RFC 6570 para Design de APIs

Aprenda a definir e expandir templates de URI usando a RFC 6570. Um padrão essencial para construir APIs RESTful robustas e flexíveis.

2026-04-11

Templates de URI Explicados: Domine a RFC 6570

Ao construir APIs RESTful, um dos conceitos mais importantes é como representar recursos usando URIs. Hardcodear URLs é frágil e leva a pesadelos de manutenção. A RFC 6570 (URI Template) fornece uma maneira padronizada de descrever uma URI com espaços reservados (placeholders) que podem ser expandidos em uma URI final.

Neste guia, mergulharemos em como os templates de URI funcionam, os diferentes tipos de expressão e por que eles são essenciais para o desenvolvimento web moderno.

O que é um Template de URI?

Um Template de URI é uma string que contém variáveis envolvidas por chaves {}. Essas variáveis são substituídas por valores reais durante um processo chamado expansão.

Exemplo Básico:

Template: http://api.example.com/users/{id} Variáveis: { "id": "123" } Expansão: http://api.example.com/users/123

Os 8 Níveis de Templates de URI

A RFC 6570 define vários níveis de complexidade para expansão. Aqui estão os mais comuns:

1. Expansão de String Simples {var}

Usado para segmentos de caminho simples.

  • Template: /{var}
  • Valores: {"var": "valor"}
  • Resultado: /valor

2. Expansão de Caracteres Reservados {+var}

Semelhante à expansão simples, mas permite caracteres reservados (como /, ?, #) sem codificá-los em porcentagem.

  • Template: /{+path}/index.html
  • Valores: {"path": "foo/bar"}
  • Resultado: /foo/bar/index.html

3. Expansão de Fragmento {#var}

Usado para fragmentos de URI (âncoras).

  • Template: {#var}
  • Valores: {"var": "secao1"}
  • Resultado: #secao1

4. Expansão de Rótulo com Ponto {.var}

Comumente usado para extensões de arquivo.

  • Template: /config{.format}
  • Valores: {"format": "json"}
  • Resultado: /config.json

5. Expansão de Segmento de Caminho {/var}

Adiciona automaticamente uma barra inicial.

  • Template: {/var}
  • Valores: {"var": "user"}
  • Resultado: /user

6. Expansão de Parâmetros de Consulta {?var}

O tipo mais comum para busca e filtragem em APIs.

  • Template: /busca{?q,lang}
  • Valores: {"q": "teste", "lang": "pt"}
  • Resultado: /busca?q=teste&lang=pt

Modificadores de Variáveis

Os Templates de URI também suportam modificadores para controlar como as variáveis são expandidas.

  • Explode (*): Usado para arrays ou objetos.
    • Template: /users{?id*}
    • Valores: {"id": [1, 2, 3]}
    • Resultado: /users?id=1&id=2&id=3
  • Prefixo (:n): Pega apenas os primeiros n caracteres.
    • Template: /{var:3}
    • Valores: {"var": "abcdef"}
    • Resultado: /abc

Por que usar Templates de URI?

  1. Desacoplamento: O cliente não precisa saber como construir a URL; ele apenas precisa do template e das variáveis.
  2. HATEOAS: Essencial para Hypermedia as the Engine of Application State. Servidores podem fornecer templates em suas respostas.
  3. Consistência: Fornece uma maneira padrão de lidar com parâmetros de consulta e segmentos de caminho em diferentes linguagens de programação e bibliotecas.

Perguntas Frequentes FAQ

P: {var} é o mesmo que :var usado em muitos roteadores? R: Conceitualmente sim, mas a RFC 6570 é o padrão oficial de como eles devem ser representados em documentação e hipermídia. A maioria dos roteadores (como Express ou React Router) usa uma sintaxe proprietária simplificada.

P: Como lidar com caracteres reservados? R: Por padrão, a expansão simples {var} irá codificar em porcentagem os caracteres reservados. Use {+var} se quiser mantê-los como estão.

P: Os templates de URI diferenciam maiúsculas de minúsculas? R: De acordo com a especificação, os nomes das variáveis diferenciam maiúsculas de minúsculas. {var} e {VAR} são variáveis diferentes.

Ferramentas Relacionadas

Voltar ao blog