Plantillas URI Explicadas: Domine RFC 6570

Al construir APIs RESTful, uno de los conceptos más importantes es cómo representar los recursos mediante URIs. Hardcodear URLs es frágil y genera pesadillas de mantenimiento. RFC 6570 (URI Template) proporciona una forma estandarizada de describir una URI con marcadores de posición que pueden expandirse en una URI final.

En esta guía, profundizaremos en cómo funcionan las plantillas URI, los diferentes tipos de expresiones y por qué son esenciales para el desarrollo web moderno.

---

¿Qué es una Plantilla URI?

Una Plantilla URI es una cadena que contiene variables envueltas en llaves {}. Estas variables se reemplazan por valores reales durante un proceso llamado expansión.

Ejemplo Básico:

Plantilla: http://api.example.com/users/{id} Variables: { "id": "123" } Expansión: http://api.example.com/users/123

---

Los 8 Niveles de Plantillas URI

RFC 6570 define varios niveles de complejidad para la expansión. Aquí están los más comunes:

1. Expansión de Cadena Simple {var}

Utilizado para segmentos de ruta simples.

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

2. Expansión de Caracteres Reservados {+var}

Similar a la expansión simple, pero permite caracteres reservados (como /, ?, #) sin codificarlos en porcentaje.

• Plantilla: /{+ruta}/index.html
• Valores: {"ruta": "foo/bar"}
• Resultado: /foo/bar/index.html

3. Expansión de Fragmento {#var}

Utilizado para fragmentos de URI (anclas).

• Plantilla: {#var}
• Valores: {"var": "seccion1"}
• Resultado: #seccion1

4. Expansión de Etiqueta con Punto {.var}

Comúnmente utilizado para extensiones de archivo.

• Plantilla: /config{.formato}
• Valores: {"formato": "json"}
• Resultado: /config.json

5. Expansión de Segmento de Ruta {/var}

Añade automáticamente una barra inicial.

• Plantilla: {/var}
• Valores: {"var": "usuario"}
• Resultado: /usuario

6. Expansión de Parámetros de Consulta {?var}

El tipo más común para búsquedas y filtrado en APIs.

• Plantilla: /buscar{?q,lang}
• Valores: {"q": "test", "lang": "es"}
• Resultado: /buscar?q=test&lang=es

---

Modificadores de Variables

Las plantillas URI también admiten modificadores para controlar cómo se expanden las variables.

• Explode (*): Utilizado para arrays u objetos.
  • Plantilla: /usuarios{?id*}
  • Valores: {"id": [1, 2, 3]}
  • Resultado: /usuarios?id=1&id=2&id=3
• Prefijo (:n): Solo toma los primeros n caracteres.
  • Plantilla: /{var:3}
  • Valores: {"var": "abcdef"}
  • Resultado: /abc

---

¿Por qué usar Plantillas URI?

1. Desacoplamiento: El cliente no necesita saber cómo construir la URL; solo necesita la plantilla y las variables.
2. HATEOAS: Esencial para Hypermedia como Motor del Estado de la Aplicación. Los servidores pueden proporcionar plantillas en sus respuestas.
3. Consistencia: Proporciona una forma estándar de manejar parámetros de consulta y segmentos de ruta a través de diferentes lenguajes de programación y librerías.

---

Preguntas frecuentes FAQ

P: ¿Es {var} lo mismo que :var usado en muchos frameworks? A: Conceptualmente sí, pero RFC 6570 es el estándar oficial de cómo deben representarse en documentación e hipermedia. La mayoría de los enrutadores (como Express o React Router) utilizan una sintaxis propietaria simplificada.

P: ¿Cómo manejo los caracteres reservados? A: Por defecto, la expansión simple {var} codificará en porcentaje los caracteres reservados. Use {+var} si desea mantenerlos tal cual.

P: ¿Las plantillas URI distinguen entre mayúsculas y minúsculas? A: Los nombres de las variables distinguen entre mayúsculas y minúsculas según la especificación. {var} y {VAR} son variables diferentes.

---

Herramientas relacionadas

• Codificador/Decodificador de URL - Compruebe cómo se codifican los caracteres durante la expansión de la plantilla.
• Formateador JSON - Formatee los datos JSON que utiliza para rellenar sus plantillas.
• Probador de Regex - Pruebe los patrones que utiliza para validar segmentos de URI.