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

Les templates URI expliqués : Maîtrisez la RFC 6570 pour la conception d'API

Apprenez à définir et à étendre des modèles d'URI à l'aide de la RFC 6570. Un standard indispensable pour créer des API RESTful robustas et flexibles.

2026-04-11

Les templates URI expliqués : Maîtriser la RFC 6570

Lors de la construction d'API RESTful, l'un des concepts les plus importants est la manière de représenter les ressources à l'aide d'URI. Coder les URL en dur est fragile et mène à des cauchemars de maintenance. La RFC 6570 (URI Template) fournit une méthode standardisée pour décrire une URI avec des espaces réservés qui peuvent être étendus en une URI finale.

Dans ce guide, nous allons approfondir le fonctionnement des modèles d'URI, les différents types d'expressions et pourquoi ils sont essentiels pour le développement Web moderne.

Qu'est-ce qu'un template URI ?

Un template URI est une chaîne de caractères qui contient des variables entourées d'accolades {}. Ces variables sont remplacées par des valeurs réelles lors d'un processus appelé expansion.

Exemple de base :

Modèle : http://api.example.com/users/{id} Variables : { "id": "123" } Expansion : http://api.example.com/users/123

Les 8 niveaux de templates URI

La RFC 6570 définit plusieurs niveaux de complexité pour l'expansion. Voici les plus courants :

1. Expansion de chaîne simple {var}

Utilisé pour les segments de chemin simples.

  • Modèle : /{var}
  • Valeurs : {"var": "valeur"}
  • Résultat : /valeur

2. Expansion de caractères réservés {+var}

Similaire à l'expansion simple, mais autorise les caractères réservés (comme /, ?, #) sans les encoder en pourcentage.

  • Modèle : /{+path}/index.html
  • Valeurs : {"path": "foo/bar"}
  • Résultat : /foo/bar/index.html

3. Expansion de fragment {#var}

Utilisé pour les fragments d'URI (ancres).

  • Modèle : {#var}
  • Valeurs : {"var": "section1"}
  • Résultat : #section1

4. Expansion d'étiquette avec point {.var}

Couramment utilisé pour les extensions de fichiers.

  • Modèle : /config{.format}
  • Valeurs : {"format": "json"}
  • Résultat : /config.json

5. Expansion de segment de chemin {/var}

Ajoute automatiquement une barre oblique de début.

  • Modèle : {/var}
  • Valeurs : {"var": "user"}
  • Résultat : /user

6. Expansion de paramètres de requête {?var}

Le type le plus courant pour la recherche et le filtrage d'API.

  • Modèle : /recherche{?q,lang}
  • Valeurs : {"q": "test", "lang": "fr"}
  • Résultat : /recherche?q=test&lang=fr

Modificateurs de variables

Les templates URI prennent également en charge des modificateurs pour contrôler la manière dont les variables sont étendues.

  • Explode (*) : Utilisé pour les tableaux ou les objets.
    • Modèle : /users{?id*}
    • Valeurs : {"id": [1, 2, 3]}
    • Résultat : /users?id=1&id=2&id=3
  • Prefix (:n) : Ne prend que les n premiers caractères.
    • Modèle : /{var:3}
    • Valeurs : {"var": "abcdef"}
    • Résultat : /abc

Pourquoi utiliser des templates URI ?

  1. Découplage : Le client n'a pas besoin de savoir comment construire l'URL ; il a juste besoin du modèle et des variables.
  2. HATEOAS : Essentiel pour Hypermedia as the Engine of Application State. Les serveurs peuvent fournir des modèles dans leurs réponses.
  3. Cohérence : Fournit une méthode standard pour gérer les paramètres de requête et les segments de chemin à travers différents langages et bibliothèques.

FAQ

Q : Est-ce que {var} est la même chose que :var utilisé dans de nombreux routeurs ? R : Conceptuellement oui, mais la RFC 6570 est le standard officiel pour la représentation dans la documentation et l'hypermédia. La plupart des routeurs (comme Express ou React Router) utilisent une syntaxe propriétaire simplifiée.

Q : Comment gérer les caractères réservés ? R : Par défaut, l'expansion simple {var} encode en pourcentage les caractères réservés. Utilisez {+var} si vous souhaitez les conserver tels quels.

Q : Les modèles d'URI sont-ils sensibles à la casse ? R : Selon la spécification, les noms de variables sont sensibles à la casse. {var} et {VAR} sont des variables différentes.

Outils connexes

  • Encodeur/Décodeur URL - Vérifiez comment les caractères sont encodés lors de l'expansion du modèle.
  • Formateur JSON - Formatez les données JSON que vous utilisez pour remplir vos modèles.
  • Testeur Regex - Testez les modèles que vous utilisez pour valider les segments d'URI.
Retour au blog