Auf der Vision, REST API-Namenskonventionen klar und verständlich zu gestalten.
Was ist eine REST-API?
REST API steht für Representational State Transfer Application Programming Interface. Es ist ein mächtiges Werkzeug, das verschiedenen Softwareanwendungen ermöglicht, über das Web zu kommunizieren, indem es standardisierte HTTP-Methoden wie GET, POST, PUT, Patch und DELETE verwendet.
REST-APIs machen es einfacher, mit Ressourcen zu arbeiten und sie zu verwalten. Sie ermöglichen einen nahtlosen Datenaustausch sowie die Integration zwischen verschiedenen Systemen.
Die Bedeutung von Namenskonventionen
Beim Entwurf einer REST-API kann die Art und Weise, wie Sie Ihre Ressourcen benennen, erheblichen Einfluss auf die Klarheit und Benutzerfreundlichkeit Ihrer API haben. Eine strukturierte Namenskonvention hilft, eine klare Beziehung zwischen Ihren Ressourcen und den HTTP-Methoden herzustellen, die mit ihnen interagieren.
In diesem Blogbeitrag werden wir die Kunst der REST-API-Namenskonventionen erkunden und beispielhafte und bewährte Praktiken anbieten, die Ihnen helfen, APIs zu erstellen, die klar und benutzerfreundlich beschrieben sind. Egal, ob Sie gerade erst anfangen oder Ihre Können verfeinern möchten. Dieser Beitrag wird Ihnen helfen, Ihre API benutzerfreundlicher und angenehmer in der Nutzung zu gestalten.
HTTP-Methoden und Ressourcen
GET: Ruft eine Ressource ab.
POST: Erstellt eine neue Ressource.
PUT: Aktualisiert eine bestehende Ressource.
PATCH: Nimmt teilweise Änderungen an einer Ressource vor.
DELETE: Löscht eine Ressource.
Grundlagen der REST-API-Namensgebung
Durch die Kategorisierung von Ressourcen in Archetypen ist die Erstellung eines konsistenten und intuitiven Namensschemas möglich. Dieser Ansatz vereinfacht nicht nur den Entwurfsprozess der API, sondern erleichtert auch Entwicklern das Verständnis und die effektive Nutzung Ihrer API.
Betrachtet man wie verschiedene HTTP-Methoden mit Ressourcen interagieren, helfen Konventionen dabei, die Funktionalität der API klar und verständlich zu präsentieren.
Eine durchdachte Namensstrategie sorgt dabei für Struktur in der API, was die Navigation und Wartung erheblich erleichtert.
Aber was sind nun Ressourcen ?
Während wir zur Darstellung von Ressourcen immer Substantive verwenden, ist eine Ressource in RESTful-APIs ein beliebiges Objekt oder eine beliebige Information, auf die über die API zugegriffen werden kann oder die manipuliert werden kann. Gängige Beispiele für Ressourcen: Benutzer, Aufträge, Produkte.…
Der Zugriff auf Ressourcen erfolgt über URIs (Unified Resource Identifiers).
<aside> ⚠️ Zur Auffrischung:
URIs können URLs und URNs sein
URNs: Uniform Resource Names : (Zur Identifizierung einer Ressource anhand des Namens und ohne Informationen über den Standort)
URLs: Uniform Resource Locators (Zur Identifizierung der Ressource im Web)
Beispiel URL: http://example.com/project/5 URN: isbn: 978-3-16-148410-0
Alle URNs und alle URLs sind URIs, aber nicht alle URIs sind URNs oder URLs.
</aside>
Wie bereits angekündigt sind Ressourcen vom typ singleton oder collection.
Beispiel singleton: /products collection: /products/{product-id}
Außerdem kann eine Ressource eine sub-collection-Ressource enthalten, wie im folgenden Beispiel “courses”:
/students/{student-id}/courses
Wie du vermutlich bemerkt hast, erkennen wir hier students als eine Collection-Ressource und student-id als eine Singleton-Ressource.
Nun lass und singleton und collection zu den folgenden Kategorien zuordnen
Die drei Kategorien einer Ressource:
Document
Collection
Store
Lasst und gemeinsam die Bedeutung der einzelnen Kategorien entschlüsseln:
Document
Die Dokument-Ressource ist eine Singleton-Ressource und daher an ihrer eindeutigen Benennung zu erkennen - daher immer im Singular. Sie ist die einzige Ressource einer Ressourcensammlung.
Beispiel device-id ist ein Document. ”http://api.example.com/device-management/managed-devices/{`device-id`}”
Collection
Eine Collection-Ressource funktioniert wie ein Verzeichnis, das zusammengehörige Ressourcen gruppiert und vom Server verwaltet wird
Nutzer können die Aufnahme neuer Ressourcen in eine Sammlung beantragen, aber die Entscheidung, eine neue Ressource zu erstellen und aufzunehmen, liegt bei der Sammlung selbst.
Die Collection-Ressource bestimmt sowohl den Inhalt, den sie enthält, als auch die spezifischen URIs, die jeder darin enthaltenen Ressource zugewiesen werden.
Beispiel /projects/{projectid}
projects := Collection projectid := Document
Store
Eine Store-Ressource ermöglicht einem API-Client das Hinzufügen, Entfernen und Löschen von Ressourcen in der Store-Ressource. Es ist jedoch wichtig zu wissen, dass keine neue Ressource im System erstellt wird, wenn etwas zum Store hinzugefügt wird. Genauso wenig wird die Ressource aus dem System gelöscht, wenn wir etwas aus Store löschen.
Mit anderen Worten, es ist gleichbedeutend mit dem Entfernen einer Verknüpfung der Ressource aus dem Store.
Store-Ressourcen stehen immer im Plural.
Beispiel /song-management/users/{id}/playlists
Benennung von URLs
Beschreibe Ressourcen in URLs immer in Kleinbuchstaben :
Beispiel http://api.example.org/my-folder/my-doc // gut HTTP://API.EXAMPLE.ORG/my-folder/my-doc // gut http://api.example.org/My-Folder/my-doc // nicht gut
Verwende nie Dateiendungen:
Beispiel /device-management/managed-devices.xml // nicht gut /device-management/managed-devices // gut
Verzichte auf Verben
⇒ Verzichte auf die Nutzung der CRUD-Funktionen in URIs, da es Redundanz verringert. Jede HTTP Methode beschreibt an sich bereits was es tut.
Beispiel HTTP GET: /device-management/get-devices // nicht gut HTTP GET: /device-management/managed-devices // gut HTTP PUT: **/device-management/create-devices // nicht gut HTTP PUT: /device-management/managed-devices // gut
Verwendung von Trennzeichen
“/” : Use only to indicate hierarchical relationships. Don’t end the URL with “/”.
“-”: Use to increase readability in namings
Don’t use “_” : Why? ⇒Depending on the application’s font, it is possible that the underscore (_) character can either get partially obscured or completely hidden in some browsers or screens. To avoid this confusion, use hyphens (-) instead of underscores ( _ ).
“/”
Verwende es nur, um auf hierarchische Beziehungen hinzuweisen. Schließedie URI nie mit einem „/“ ab.
“-”
Verwendung zur Verbesserung der Lesbarkeit von Bezeichnungen.
Verzichte auf “_”
Unterstriche können je nach Schriftart oder Bildschirmauflösung schwer zu erkennen oder sogar unsichtbar sein.
Zusammenfassung
Hier sind nochmal alle wichtigen Punkte zusammengefasst:
Definition von Ressourcen: Wir haben das Konzept der Ressourcen in REST-APIs erläutert und dabei zwischen Collection und Singleton unterschieden und gezeigt, wie Ressourcen weiter in Document, Collection und Store zugerdnet werden können.
Definition der drei Hauptkategorien:
Document: Repräsentiert eine einzelne Ressource
Collection: Ein Verzeichnis von Ressourcen
Store: Eine Ressource, die es ermöglicht, Ressourcen hinzuzufügen oder zu entfernen, ohne den Kernbestand des Systems zu verändern.
Bewährte Praktiken für die URI-Benennung
Ressourcen in URIs werden immer klein geschrieben
Verzicht auf Dateiendungen
Verzicht auf Verben
Durch die Einhaltung dieser Namenskonventionen und den bewährten Praktiken können Entwickler REST-APIs erstellen, die nicht nur funktionaler, sondern auch einfacher zu navigieren und zu pflegen sind. Dieser strukturierte Ansatz für die Namensgebung stellt sicher, dass APIs klar und vorhersehbar sind, was den Weg für eine reibungslose Integration und eine bessere allgemeine Nutzerfreundlichkeit ebnet.
Comments