POST alleen? Laten we dit absurde debat over API-ontwerp beëindigen

Recentelijk trok een discussie over het ontwerpen van API's met "alleen POST" mijn aandacht. Na me in dit debat te hebben verdiept, ontdekte ik dat niet alleen het onderwerp waarover mensen discussiëren zinloos is, maar dat het ook een misverstand van veel ontwikkelaars over de essentie van API-ontwerp blootlegt. Vandaag duiken we diep in de kernideeën van API-ontwerp en zien we waarom dit debat in de eerste plaats niet zou moeten bestaan.

Het misverstand van "alleen POST"#

Die ontwikkelaars die pleiten voor het gebruik van "alleen POST" ter vervanging van de RESTful API-specificaties, hebben duidelijk het belangrijkste punt van API-ontwerp niet begrepen. Hun argumenten omvatten meestal:

1. Vereenvoudiging van ontwerp: Eén methode kan alles afhandelen
2. Veiligheid: POST parameters verschijnen niet in de URL
3. Flexibiliteit: POST kan elke datastructuur verzenden

Op het eerste gezicht lijken deze argumenten enigszins logisch. Maar in werkelijkheid verwart deze opvatting de keuze van HTTP-methoden met API-ontwerptypen, twee verschillende niveaus van problemen. POST is slechts één methode van het HTTP-protocol, terwijl REST een stijl van API-ontwerp is.

De essentie van API-ontwerp#

Voordat we specifieke API-stijlen bespreken, moeten we begrijpen wat het kerndoel van API-ontwerp is. Een goede API moet zijn:

1. Helder en begrijpelijk: Andere ontwikkelaars (inclusief je toekomstige zelf) moeten intuïtief het doel van elk eindpunt kunnen begrijpen
2. Consistent: Bepaalde specificaties volgen om de leerkosten te verminderen
3. Uitbreidbaar: In staat om eenvoudig versiebeheer en functionele uitbreiding uit te voeren
4. Efficiënt: Overweeg efficiëntie in termen van prestaties en middelengebruik

RESTful API: Meer dan alleen een keuze van HTTP-methoden#

RESTful API is slechts een van vele API-ontwerptypen, met de focus op bronnen en bewerkingen op bronnen. Laten we een eenvoudig blogsysteem als voorbeeld nemen om te zien hoe een RESTful API is ontworpen:

1. Alle artikelen ophalen:

2. Een specifiek artikel ophalen:

3. Een nieuw artikel maken:

4. Een artikel bijwerken:

5. Een artikel verwijderen:

In dit voorbeeld kunnen we zien:

• De API is ontworpen rond de "artikel" bron
• Verschillende HTTP-methoden worden gebruikt om verschillende bewerkingen te vertegenwoordigen
• De URL-structuur is duidelijk, wat aangeeft op welke bron wordt geoperereerd

Deze ontwerpbenadering maakt de API intuïtiever en zelfverklarend, waardoor het gemakkelijk is voor ontwikkelaars om de functie van elk eindpunt te begrijpen.

RPC: Het API-stijl begrijpen achter "alleen POST"#

Het doel van RPC (Remote Procedure Call) stijl API-ontwerp is om externe serviceaanroepen te laten lijken op het oproepen van lokale functies.

Interessant genoeg realiseren degenen die pleiten voor "alleen POST" zich misschien niet dat ze eigenlijk de RPC-stijl beschrijven.

In vergelijking met RESTful-API's richt RPC zich meer op de bewerking zelf dan op de bron. Daarom gebruiken RPC-stijl-API's doorgaans een "werkwoord + zelfstandig naamwoord" vorm, zoals getProduct(productId) of createUser(userData).

In veel RPC-implementaties worden alle bewerkingen meestal via POST-verzoeken naar hetzelfde eindpunt verzonden, met vermelding van de specifieke bewerking en parameters in de body van het verzoek. Dit is waarom het idee van "alleen POST" eigenlijk dichter bij RPC dan REST staat.

Bijvoorbeeld, een RPC-stijl "product ophalen" verzoek gebaseerd op HTTP zou er als volgt uit kunnen zien:

Moderne RPC-frameworks, zoals gRPC, bieden krachtigere en efficiëntere implementaties. Laten we dit als voorbeeld nemen om de RPC-stijl te demonstreren:

Eerst definiëren we de service en het berichtformaat (met Protocol Buffers):

Vervolgens is het gebruik van deze service in een Node.js-client net zo eenvoudig als het aanroepen van een lokale functie:

In dit RPC-stijl voorbeeld kunnen we zien:

1. De servicedefinitie vermeldt duidelijk alle beschikbare operaties (in dit vereenvoudigde voorbeeld GetArticle en CreateArticle).
2. Elke operatie heeft duidelijk gedefinieerde aanvraag- en antwoordtypen.
3. De clientcode lijkt op het oproepen van een lokale asynchrone functie, waarbij await wordt gebruikt om op het resultaat te wachten, wat verder de complexiteit van netwerkcommunicatie verbergt.
4. Er is geen behoefte om handmatig HTTP-verzoeken te construeren of JSON-antwoorden te parseren.

Hoewel de onderliggende laag mogelijk nog steeds HTTP/2 als transportprotocol gebruikt, bieden RPC-frameworks (zoals gRPC) ontwikkelaars een abstractielaag die externe oproepen laat lijken en voelen als lokale functieoproepen.

Daarom kunnen we zien dat de meeste discussies over "alleen POST" en RESTful-API's in wezen discussies zouden moeten zijn over deze twee API-stijlen: REST en RPC. Het belangrijkste is echter om te erkennen dat deze twee stijlen elk hun toepassingsscenario's hebben en dat de keuze moet worden gebaseerd op de specifieke behoeften van het project, niet persoonlijke voorkeur.

REST vs RPC: Geen absolute superioriteit of inferioriteit#

Nu we de verschillen tussen REST en RPC begrijpen, laten we eens kijken naar hun respectieve toepasselijke scenario's:

1. REST is geschikt voor:
   • Bron-georiënteerde applicaties (zoals contentbeheersystemen, blogplatforms, e-commerce websites)
   • Scenario's die goede cache-ondersteuning vereisen (GET-verzoeken zijn van nature cachebaar)
   • Projecten die gebruik willen maken van HTTP-semantiek (zoals het gebruik van geschikte statuscodes)
   • Publiekgerichte API's die goede vindbaarheid en zelfbeschrijving vereisen
2. RPC is geschikt voor:
   • Actie-georiënteerde applicaties (zoals complexe gegevensverwerkingsbewerkingen, workflowcontrole)
   • Systemen die hoge prestaties en lage latentie vereisen (zoals realtime handelssystemen)
   • Communicatie tussen interne microservices (die mogelijk flexibeler parameter doorgifte vereisen)
   • Wanneer operaties niet eenvoudig kunnen worden gemapt naar CRUD (Create, Read, Update, Delete) operaties

De keuze van stijl moet gebaseerd zijn op uw specifieke behoeften. In sommige gevallen kunt u zelfs een mix van deze twee stijlen gebruiken binnen hetzelfde systeem om aan de behoeften van verschillende delen te voldoen.

Conclusie#

1. De kern van API-ontwerp ligt in helderheid, consistentie, uitbreidbaarheid en efficiëntie, niet in het vasthouden aan een bepaalde methode of stijl.
2. Zowel RESTful als RPC zijn volwassen API-ontwerpparadigma's. De keuze tussen hen moet gebaseerd zijn op projectvereisten, niet op persoonlijke voorkeur.
3. Als je besluit "alleen POST" te gebruiken, ontwerp je API dan volgens de RPC-stijl. Net als RESTful is het een veelgebruikte API-specificatie in de industrie, maar het moet worden gebruikt in geschikte scenario's.
4. Laat je niet verwarren door oppervlakkige technische details. Wat echt belangrijk is, is of je API effectief je gebruikers en bedrijfsbehoeften kan bedienen.
5. Besteed bij het ontwerpen van API's meer tijd aan het nadenken over je bronnenmodel, bedrijfslogica en gebruikersbehoeften, in plaats van je te laten obsederen door welke HTTP-methode je moet gebruiken.

Laten we onze aandacht weghalen van deze zinloze argumenten en ons concentreren op het ontwerpen van echt uitstekende API's. Uiteindelijk is technologie er om problemen op te lossen, niet om ze te creëren.