Richten Sie REST-API-Endpunkte korrekt ein?

Stellst du deine REST-API-Endpoints richtig ein?

Stellst du deine API-Endpoints richtig ein? Häufig stoßen wir beim Einrichten von Endpoints für unsere APIs auf Situationen, in denen wir uns nicht sicher sind, ob wir die Pluralform oder Singularform verwenden sollten. Sollten wir Unterstriche oder Bindestriche verwenden? Wie erwähnen wir IDs? Für eine API, die eine Ressource erstellt, sollten wir /resource/create verwenden? Und vieles mehr. Lass uns also einen tieferen Blick auf die Namenskonvention für REST-APIs werfen. Hier behandeln wir:

• Endpoints
• Methoden
• Versionierung

Endpoints

Lass uns damit beginnen, einige REST-API-Namenskonventionen durchzugehen.

Ressourcen als Substantive

REST-APIs sollten dir ermöglichen, eine Ressource zu bearbeiten, indem du eine der wichtigsten HTTP-Methoden verwendest. Die REST-URIs sollten keine CRUD-Operationen andeuten. Sie sollten auf eine Ressource verweisen, anstatt auf eine Aktion oder ein Verb. Verwende, wenn möglich, nur Pluralformen von Substantiven, es sei denn, es handelt sich um Singleton-Ressourcen.

Gute Beispiele:

• https://api.website.com/v1/store/products
• https://api.website.com/v1/store/customers
• https://api.website.com/v1/store/discounts

Schlechte Beispiele:

• https://api.website.com/v1/store/createproducts
• https://api.website.com/v1/store/updatecustomers
• https://api.website.com/v1/store/getdiscounts

Hierarchie

Die Hierarchie zwischen Ressourcen und Sammlungen wird durch die Verwendung von Schrägstrichen definiert.

"Wie bei allem in der Softwareentwicklung ist die Benennung entscheidend für den Erfolg"

Gutes Beispiel:

• https://api.website.com/v1/item/store

Schlechtes Beispiel:

• https://api.website.com/v1/store/items

Bindestriche

Es ist allgemein anerkannt, dass Bindestriche ( first-name ) deutlicher und benutzerfreundlicher zu lesen sind als Unterstriche ( first_name ). Daher ist es immer besser, Bindestriche anstelle von Unterstrichen zu verwenden, wenn ein REST-API-Endpoint mehrere Wörter enthält. Außerdem gibt es hier auch einen Aspekt aus SEO-Perspektive. Es wird empfohlen, Bindestriche zu verwenden, da sie Bots helfen, die Konzepte in der URL leichter zu identifizieren. Ein Unterstrich zwischen zwei Wörtern wird als ganzes Wort betrachtet, während Bindestriche als zwei separate Wörter gelten.

Gutes Beispiel:

• https://api.website.com/v1/store/inventory-management/active-orders

Schlechtes Beispiel

• https://api.website.com/v1/store/inventory_management/active_orders

Methoden

Wir wissen jetzt, dass wir keine Verben in unseren REST-API-Endpoints verwenden sollten, aber das wirft die Frage auf, wie man das Verb dann spezifiziert. Dafür haben wir HTTP-Methoden. HTTP-Methoden sind die Verben, die die Art der Operation angeben, die die API ausführen könnte.

HTTP-Methoden:

• GET entspricht der "Lese"-Operation einer Ressource oder Sammlung.
• POST entspricht der "Erstell"-Operation einer Ressource oder Sammlung.
• PUT entspricht der "Aktualisierungs"-Operation einer Ressource oder Sammlung.
• DELETE entspricht der "Lösch"-Operation einer Ressource oder Sammlung.

Es gibt insgesamt 39 HTTP-Methoden, aber GET, POST, PUT und DELETE sind die am häufigsten verwendeten und grundlegenden Methoden. Wir werden alle HTTP-Methoden und ihre Anwendungsfälle in einem separaten Blog behandeln.

Versionierung

Es ist immer besser, deine APIs zu versionieren. Die gleichen URLs können genutzt werden, ohne dass große Änderungen an den REST-API-Endpoints vorgenommen werden müssen. API-Endpoints sollten niemals ungültig gemacht werden, da dies unvorhergesehene Folgen für die Anwendungen haben könnte, die sie nutzen.

Beispiele:

• https://api.website.com/v1/store/items
• https://api.webiste.com/v2/store/employees

Wichtigste Punkte

• Verwende Substantive, um Ressourcen darzustellen.
• Vermeide die Verwendung von Verben in den REST-API-Endpoints.
• Verwende keine Unterstriche (`_`) in einem Endpoint. Verwende stattdessen Bindestriche (`-`).
• Verwende Abfragen, um eine API-Sammlung zu filtern, zu sortieren oder zu begrenzen.
• Füge URLs niemals Dateierweiterungen hinzu. Wenn du den Inhaltstyp spezifizieren möchtest, verwende den `Content-Type` Header.
• Verwende immer Kleinbuchstaben in den REST-API-Endpoints.
• Füge keine nachfolgenden Schrägstriche (`/`) in den REST-API-Endpoints ein. Sie haben keinen semantischen Wert und können verwirrend sein.
• Wähle einfache Namen. Wenn es richtig gemacht wird, werden API-Endpoints sehr leicht zu merken oder zu erraten sein.