URI-Template erklärt: Meistern Sie RFC 6570

Beim Aufbau von RESTful APIs ist eines der wichtigsten Konzepte, wie Ressourcen mithilfe von URIs dargestellt werden. Das Hardcodieren von URLs ist unflexibel und führt zu Wartungsproblemen. RFC 6570 (URI Template) bietet eine standardisierte Methode zur Beschreibung einer URI mit Platzhaltern, die zu einer endgültigen URI erweitert werden können.

In diesem Leitfaden werden wir tief in die Funktionsweise von URI-Templates, die verschiedenen Ausdruckstypen und die Gründe eintauchen, warum sie für die moderne Webentwicklung unerlässlich sind.

---

Was ist ein URI-Template?

Ein URI-Template ist ein String, der in geschweiften Klammern {} eingeschlossene Variablen enthält. Diese Variablen werden während eines Prozesses, der als Expansion (Erweiterung) bezeichnet wird, durch tatsächliche Werte ersetzt.

Basispiel:

Template: http://api.example.com/users/{id} Variablen: { "id": "123" } Expansion: http://api.example.com/users/123

---

Die 8 Stufen von URI-Templates

RFC 6570 definiert verschiedene Komplexitätsstufen für die Expansion. Hier sind die gängigsten:

1. Einfache String-Expansion {var}

Wird für einfache Pfadsegmente verwendet.

• Template: /{var}
• Werte: {"var": "value"}
• Ergebnis: /value

2. Expansion reservierter Zeichen {+var}

Ähnlich wie die einfache Expansion, erlaubt aber reservierte Zeichen (wie /, ?, #), ohne sie prozentual zu kodieren.

• Template: /{+path}/index.html
• Werte: {"path": "foo/bar"}
• Ergebnis: /foo/bar/index.html

3. Fragment-Expansion {#var}

Wird für URI-Fragmente (Anker) verwendet.

• Template: {#var}
• Werte: {"var": "section1"}
• Ergebnis: #section1

4. Label-Expansion mit Punkt {.var}

Wird häufig für Dateiendungen verwendet.

• Template: /config{.format}
• Werte: {"format": "json"}
• Ergebnis: /config.json

5. Pfadsegment-Expansion {/var}

Fügt automatisch einen führenden Schrägstrich hinzu.

• Template: {/var}
• Werte: {"var": "user"}
• Ergebnis: /user

6. Query-Parameter-Expansion {?var}

Der häufigste Typ für API-Suchen und -Filterungen.

• Template: /search{?q,lang}
• Werte: {"q": "test", "lang": "de"}
• Ergebnis: /search?q=test&lang=de

---

Variablen-Modifikatoren

URI-Templates unterstützen auch Modifikatoren, um zu steuern, wie Variablen erweitert werden.

• Explode (*): Wird für Arrays oder Objekte verwendet.
  • Template: /users{?id*}
  • Werte: {"id": [1, 2, 3]}
  • Ergebnis: /users?id=1&id=2&id=3
• Präfix (:n): Nimmt nur die ersten n Zeichen.
  • Template: /{var:3}
  • Werte: {"var": "abcdef"}
  • Ergebnis: /abc

---

Warum URI-Templates verwenden?

1. Entkopplung: Der Client muss nicht wissen, wie die URL konstruiert wird; er benötigt lediglich das Template und die Variablen.
2. HATEOAS: Unerlässlich für Hypermedia as the Engine of Application State. Server können Templates in ihren Antworten bereitstellen.
3. Konsistenz: Bietet eine standardisierte Methode zur Handhabung von Query-Parametern und Pfadsegmenten über verschiedene Programmiersprachen und Bibliotheken hinweg.

---

Häufig gestellte Fragen FAQ

F: Ist {var} dasselbe wie :var, das in vielen Routern verwendet wird? A: Konzeptuell ja, aber RFC 6570 ist der offizielle Standard dafür, wie diese in der Dokumentation und in Hypermedia dargestellt werden sollten. Die meisten Router (wie Express oder React Router) verwenden eine vereinfachte proprietäre Syntax.

F: Wie gehe ich mit reservierten Zeichen um? A: Standardmäßig wird die einfache Expansion {var} reservierte Zeichen prozentual kodieren. Verwenden Sie {+var}, wenn Sie diese unverändert beibehalten möchten.

F: Unterscheiden URI-Templates zwischen Groß- und Kleinschreibung? A: Laut Spezifikation wird bei Variablennamen zwischen Groß- und Kleinschreibung unterschieden. {var} und {VAR} sind unterschiedliche Variablen.

---

Verwandte Tools

• URL-Kodierer/Dekodierer – Überprüfen Sie, wie Zeichen während der Template-Expansion kodiert werden.
• JSON-Formatierer – Formatieren Sie die JSON-Daten, die Sie zum Füllen Ihrer Templates verwenden.
• Regex-Tester – Testen Sie die Muster, die Sie zur Validierung von URI-Segmenten verwenden.