Stellen Sie Ihre REST-API-Endpunkte richtig ein?

Setzen Sie REST API-Endpunkte richtig ein?

Setzen Sie Ihre API-Endpunkte richtig ein? Häufig stehen wir beim Einrichten von Endpunkten für unsere APIs vor der Frage, ob wir die Pluralform oder Singularform verwenden sollen. Sollten wir Unterstriche oder Bindestriche verwenden? Wie mention man IDs? Für eine API, die eine Ressource erstellt, sollten wir /resource/create verwenden? Und vieles mehr. Lassen Sie uns also einen tieferen Blick auf die Namenskonvention für REST APIs werfen. Hier werden wir Folgendes behandeln:

• Endpunkte
• Methoden
• Versionierung

Endpunkte

Lassen Sie uns damit beginnen, einige Namenskonventionen für REST APIs durchzugehen.

Ressourcen als Substantive

REST APIs sollten es Ihnen ermöglichen, eine Ressource mithilfe einer der wichtigsten HTTP-Methoden zu manipulieren. Die REST-URIs sollten keine CRUD-Operationen angeben. Sie sollten sich auf eine Ressource beziehen, anstatt auf eine Aktion/ein Verb. Verwenden Sie nach Möglichkeit nur Pluralformen der Substantive, 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 in jedem Handwerk 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 das Lesen von Bindestrichen ( first-name ) klarer und benutzerfreundlicher ist als das Lesen von Unterstrichen ( first_name ). Daher ist es immer besser, Bindestriche anstelle von Unterstrichen zu verwenden, wenn ein REST API-Endpunkt mehrere Wörter enthält. Außerdem gibt es hier auch einen SEO-Aspekt. Es wird empfohlen, Bindestriche zu verwenden, da dies Bots dabei hilft, die Konzepte in der URL leichter zu identifizieren. Ein Unterstrich zwischen zwei Wörtern wird als Ganzes als ein Wort betrachtet, während die Verwendung von Bindestrichen als zwei separate Wörter gilt.

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-Endpunkten verwenden sollten, aber das wirft die Frage auf, wie man das Verb dann angibt. Dafür haben wir HTTP-Methoden zur Rettung. 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 einer Sammlung.
• POST entspricht der „Erstell"-Operation einer Ressource oder einer Sammlung.
• PUT entspricht der „Aktualisierungs"-Operation einer Ressource oder einer Sammlung.
• DELETE entspricht der „Lösch"-Operation einer Ressource oder einer Sammlung.

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

Versionierung

Es ist immer besser, Ihre APIs zu versionieren. Dieselben URLs können verwendet werden, ohne dass große Änderungen an den REST API-Endpunkten vorgenommen werden müssen. API-Endpunkte sollten niemals ungültig gemacht werden, da dies unvorhergesehene Konsequenzen für die sie konsumierenden Anwendungen haben könnte.

Beispiele:

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

Wichtigste Punkte

• Verwenden Sie Substantive, um Ressourcen darzustellen.
• Vermeiden Sie die Verwendung von Verben in den REST API-Endpunkten.
• Verwenden Sie keine Unterstriche (`_`) in einem Endpunkt. Verwenden Sie stattdessen Bindestriche (`-`).
• Verwenden Sie Abfragen, um eine API-Sammlung zu filtern, zu sortieren oder zu begrenzen.
• Fügen Sie niemals Dateierweiterungen zu den URLs hinzu. Wenn Sie den Inhaltstyp angeben möchten, verwenden Sie den `Content-Type` Header.
• Bevorzugen Sie immer die Verwendung von Kleinbuchstaben in den REST API-Endpunkten.
• Fügen Sie keine nachgestellten Schrägstriche (`/`) in den REST API-Endpunkten ein. Sie fügen keinen semantischen Wert hinzu und können verwirrend sein.
• Wählen Sie einfache Namen. Wenn es richtig gemacht wird, werden API-Endpunkte sehr leicht für jeden Entwickler zu merken oder zu erraten sein.