Nur POST? Lasst uns diese absurde API-Design-Debatte beenden

Kürzlich erregte eine Diskussion darüber, ob man APIs nur mit „POST“ entwerfen sollte, meine Aufmerksamkeit. Nachdem ich mich in diese Debatte eingelesen hatte, stellte ich fest, dass die Diskussion nicht nur sinnlos ist, sondern auch das Missverständnis vieler Entwickler über das Wesen des API-Designs offenbart. Heute wollen wir tief in die Kernideen des API-Designs eintauchen und sehen, warum diese Debatte von Anfang an nicht existieren sollte.

Das Missverständnis von „Nur POST“#

Die Entwickler, die dafür plädieren, „nur POST“ zu verwenden, um RESTful API-Spezifikationen zu ersetzen, haben offensichtlich den wichtigsten Punkt des API-Designs nicht verstanden. Ihre Argumente umfassen in der Regel:

1. Vereinfachung des Designs: Eine Methode kann alles erledigen
2. Sicherheit: POST-Parameter erscheinen nicht in der URL
3. Flexibilität: POST kann beliebige Datenstrukturen senden

Auf den ersten Blick scheinen diese Argumente Sinn zu machen. In Wirklichkeit vermischen sie jedoch die Wahl der HTTP-Methoden mit API-Designstilen, zwei verschiedenen Ebenen von Problemen. POST ist nur eine Methode des HTTP-Protokolls, während REST ein Stil des API-Designs ist.

Das Wesen des API-Designs#

Bevor wir spezifische API-Stile diskutieren, müssen wir verstehen, was der Kernzweck des API-Designs ist. Eine gute API sollte:

1. Klar verständlich sein: Andere Entwickler (einschließlich deines zukünftigen Selbst) sollten intuitiv verstehen können, welchen Zweck jeder Endpunkt hat
2. Konsistent sein: Bestimmten Spezifikationen folgen, um die Lernkosten zu reduzieren
3. Erweiterbar sein: In der Lage sein, leicht eine Versionskontrolle und funktionale Erweiterungen durchzuführen
4. Effizient sein: Effizienz in Bezug auf Leistung und Ressourcennutzung berücksichtigen

RESTful API: Mehr als nur eine Wahl der HTTP-Methoden#

RESTful API ist nur einer von vielen API-Designstilen und konzentriert sich auf Ressourcen und Operationen auf Ressourcen. Nehmen wir ein einfaches Blog-System als Beispiel, um zu sehen, wie RESTful API gestaltet wird:

1. Alle Artikel abrufen:

2. Einen bestimmten Artikel abrufen:

3. Einen neuen Artikel erstellen:

4. Einen Artikel aktualisieren:

5. Einen Artikel löschen:

In diesem Beispiel können wir sehen:

• Die API ist um die Ressource „Artikel“ herum konzipiert
• Unterschiedliche HTTP-Methoden werden verwendet, um verschiedene Operationen darzustellen
• Die URL-Struktur ist klar und zeigt die Ressource an, auf die zugegriffen wird

Dieser Designansatz macht die API intuitiver und selbsterklärender und erleichtert es Entwicklern, die Funktion jedes Endpunkts zu verstehen.

RPC: Verständnis des API-Stils hinter „Nur POST“#

Das Ziel des RPC (Remote Procedure Call) API-Designstils ist es, Remote-Serviceaufrufe so einfach wie lokale Funktionsaufrufe aussehen zu lassen.

Interessanterweise erkennen diejenigen, die „nur POST“ befürworten, möglicherweise nicht, dass sie tatsächlich den RPC-Stil beschreiben.

Im Vergleich zu RESTful APIs konzentriert sich RPC stärker auf die Operation selbst als auf die Ressource. Aus diesem Grund verwenden RPC-APIs in der Regel eine „Verb + Substantiv“-Form wie getProduct(productId) oder createUser(userData).

In vielen RPC-Implementierungen werden alle Operationen in der Regel über POST-Anfragen an denselben Endpunkt gesendet, wobei die spezifische Operation und ihre Parameter im Anfragetext angegeben sind. Aus diesem Grund ist die Idee von „nur POST“ tatsächlich näher an RPC als an REST.

Ein RPC-Stil „Produkt abrufen“ basierend auf einer HTTP-Anfrage könnte so aussehen:

Moderne RPC-Frameworks, wie gRPC, bieten leistungsfähigere und effizientere Implementierungen. Lassen Sie uns dieses Beispiel verwenden, um den RPC-Stil zu demonstrieren:

Zuerst definieren wir den Dienst und das Nachrichtenformat (mithilfe von Protocol Buffers):

Dann ist die Verwendung dieses Dienstes in einem Node.js-Client so einfach wie der Aufruf einer lokalen Funktion:

In diesem RPC-Stil-Beispiel können wir sehen:

1. Die Dienstdefinition listet alle verfügbaren Operationen deutlich auf (in diesem vereinfachten Beispiel GetArticle und CreateArticle).
2. Jede Operation hat klar definierte Anfrage- und Antworttypen.
3. Der Client-Code sieht aus wie der Aufruf einer lokalen asynchronen Funktion, bei der await verwendet wird, um auf das Ergebnis zu warten, was die Komplexität der Netzwerkommunikation weiter verbirgt.
4. Es ist nicht nötig, manuell HTTP-Anfragen zu erstellen oder JSON-Antworten zu analysieren.

Obwohl die darunterliegende Schicht möglicherweise weiterhin HTTP/2 als Transportprotokoll verwendet, bieten RPC-Frameworks (wie gRPC) Entwicklern eine Abstraktionsschicht, die Remote-Aufrufe wie lokale Funktionsaufrufe aussehen lässt.

Daher können wir sehen, dass die meisten Debatten über „Nur POST“ und RESTful-APIs im Wesentlichen Diskussionen über diese beiden API-Stile sein sollten: REST und RPC. Der Schlüssel liegt jedoch darin, zu erkennen, dass diese beiden Stile jeweils ihre Anwendungsbereiche haben und die Wahl auf den spezifischen Bedürfnissen des Projekts, und nicht auf persönlichen Vorlieben, basieren sollte.

REST vs RPC: Keine absolute Über- oder Unterlegenheit#

Da wir nun die Unterschiede zwischen REST und RPC verstehen, betrachten wir ihre jeweiligen Anwendungsbereiche:

1. REST ist geeignet für:
   • Ressourcenorientierte Anwendungen (wie Content-Management-Systeme, Blog-Plattformen, E-Commerce-Websites)
   • Szenarien, die eine gute Cache-Unterstützung erfordern (GET-Anfragen sind von Natur aus cachefähig)
   • Projekte, die die Semantik von HTTP nutzen möchten (z.B. Verwendung geeigneter Statuscodes)
   • Öffentlich zugängliche APIs, die eine gute Entdeckbarkeit und Selbstbeschreibung erfordern
2. RPC ist geeignet für:
   • Aktionen-orientierte Anwendungen (wie komplexe Datenverarbeitungsoperationen, Workflow-Steuerung)
   • Systeme, die eine hohe Leistung und geringe Latenz erfordern (wie Echtzeit-Handelssysteme)
   • Kommunikation zwischen internen Mikroservices (die möglicherweise eine flexiblere Parameterübergabe erfordern)
   • Wenn Operationen nicht einfach auf CRUD (Create, Read, Update, Delete) Operationen abgebildet werden können

Die Wahl des Stils sollte auf deinen spezifischen Bedürfnissen basieren. In einigen Fällen könntest du sogar eine Mischung dieser beiden Stile innerhalb desselben Systems verwenden, um die Anforderungen verschiedener Teile zu erfüllen.

Fazit#

1. Der Kern des API-Designs liegt in Klarheit, Konsistenz, Erweiterbarkeit und Effizienz, nicht darin, sich an eine bestimmte Methode oder einen Stil zu halten.
2. Sowohl RESTful als auch RPC sind ausgereifte API-Design-Paradigmen. Die Wahl zwischen ihnen sollte auf den Anforderungen des Projekts und nicht auf persönlichen Vorlieben basieren.
3. Wenn du dich entscheidest, „nur POST“ zu verwenden, dann entwirf bitte deine API nach dem RPC-Stil. Wie RESTful ist auch dies eine weithin verwendete API-Spezifikation in der Branche, aber sie sollte in geeigneten Szenarien verwendet werden.
4. Lasse dich nicht von oberflächlichen technischen Details verwirren. Was wirklich zählt, ist, ob deine API deinen Benutzern und Geschäftsanforderungen effektiv dient.
5. Beim Entwerfen von APIs solltest du mehr Zeit darauf verwenden, über dein Ressourcenmodell, deine Geschäftslogik und die Bedürfnisse deiner Benutzer nachzudenken, anstatt dich darüber zu ärgern, welche HTTP-Methode du verwenden sollst.

Lasst uns unsere Aufmerksamkeit von diesen sinnlosen Argumenten abwenden und uns darauf konzentrieren, wirklich hervorragende APIs zu entwerfen. Schließlich ist Technologie dazu da, Probleme zu lösen, nicht sie zu schaffen.