Bara POST? Låt oss avsluta denna absurda API-designdebatt

Nyligen fångade en diskussion om huruvida man ska designa API:er med "bara POST" min uppmärksamhet. Efter att ha fördjupat mig i denna debatt fann jag att inte bara är frågan om vad folk argumenterar meningslös, utan den avslöjar också många utvecklares missförstånd av kärnan i API-design. Låt oss idag dyka djupt in i huvudidéerna med API-design och se varför denna debatt inte borde existera från första början.

Missuppfattningen om "bara POST"#

De utvecklare som förespråkar att använda "bara POST" för att ersätta RESTful API-specifikationer har tydligt inte förstått den viktigaste punkten inom API-design. Deras argument inkluderar vanligtvis:

1. Förenklar design: En metod kan hantera allt
2. Säkerhet: POST-parametrar visas inte i URL:en
3. Flexibilitet: POST kan skicka vilken datastruktur som helst

Vid en första anblick verkar dessa argument ge viss mening. Men i verkligheten förväxlar denna syn valet av HTTP-metoder med API-designstilar, två olika nivåer av problem. POST är bara en metod i HTTP-protokollet, medan REST är en stil för API-design.

Kärnan i API-design#

Innan vi diskuterar specifika API-stilar behöver vi förstå vad som är det centrala syftet med API-design. Ett bra API bör vara:

1. Tydligt och begripligt: Andra utvecklare (inklusive ditt framtida jag) bör kunna förstå syftet med varje slutpunkt intuitivt
2. Konsekvent: Följ vissa specifikationer för att minska inlärningskostnaderna
3. Utbyggbart: Kunna enkelt utföra versionskontroll och funktionell expansion
4. Effektivt: Överväga effektivitet i termer av prestanda och resursutnyttjande

RESTful API: Mer än bara ett val av HTTP-metoder#

RESTful API är bara en av många API-designstilar, med fokus på resurser och operationer på resurser. Låt oss ta ett enkelt bloggsystem som exempel för att se hur RESTful API designas:

1. Hämta alla artiklar:

2. Hämta en specifik artikel:

3. Skapa en ny artikel:

4. Uppdatera en artikel:

5. Ta bort en artikel:

I det här exemplet kan vi se:

• API:et är designat kring "artikel"-resursen
• Olika HTTP-metoder används för att representera olika operationer
• URL-strukturen är tydlig och visar vilken resurs som opereras på

Denna designmetod gör API:et mer intuitivt och självförklarande, vilket gör det enkelt för utvecklare att förstå funktionen av varje slutpunkt.

RPC: Förstå API-stilen bakom "bara POST"#

Målet med RPC (Remote Procedure Call) stil API-design är att göra fjärrtjänstanrop så enkla som att kalla lokala funktioner.

Intressant nog kanske de som förespråkar "bara POST" inte inser att de faktiskt beskriver RPC-stilen.

Jämfört med RESTful API:er fokuserar RPC mer på själva operationen snarare än resursen. Därför använder RPC-stil API:er vanligtvis en "verb + substantiv"-form, såsom getProduct(productId) eller createUser(userData).

I många RPC-implementeringar skickas alla operationer vanligen via POST-förfrågningar till samma slutpunkt, med den specifika operationen och parametrarna angivna i förfrågningskroppen. Detta är varför idén om "bara POST" faktiskt ligger närmare RPC än REST.

Till exempel kan en RPC-stil "hämta produkt"-förfrågan baserad på HTTP se ut så här:

Moderna RPC-ramverk, såsom gRPC, erbjuder kraftfullare och mer effektiva implementationer. Låt oss använda detta som ett exempel för att demonstrera RPC-stilen:

Först definierar vi tjänsten och meddelandeformatet (med hjälp av Protocol Buffers):

Sedan, med hjälp av denna tjänst i en Node.js-klient är det lika enkelt som att kalla en lokal funktion:

I detta RPC-stil exempel kan vi se:

1. Tjänstedefinitionen listar tydligt alla tillgängliga operationer (i detta förenklade exempel, GetArticle och CreateArticle).
2. Varje operation har tydligt definierade förfrågnings- och svarstyper.
3. Klientkoden ser ut som att kalla en lokal asynkron funktion, använder await för att vänta på resultatet, vilket ytterligare döljer nätverkskommunikationens komplexitet.
4. Det finns inget behov av att manuellt konstruera HTTP-förfrågningar eller tolka JSON-svar.

Även om det underliggande lagret fortfarande kan använda HTTP/2 som transportprotokoll, ger RPC-ramverk (som gRPC) utvecklare ett abstraktionslager som gör fjärranropen till att se ut och kännas som lokala funktionsanrop.

Därför kan vi se att de flesta debatter om "bara POST" och RESTful API:er egentligen borde vara diskussioner om dessa två API-stilar: REST och RPC. Nyckeln är dock att erkänna att dessa två stilar har sina tillämpliga scenarier, och valet bör baseras på projektets specifika behov, inte personliga preferenser.

REST vs RPC: Ingen absolut överlägsenhet eller underlägsenhet#

Nu när vi förstår skillnaderna mellan REST och RPC, låt oss titta på deras respektive tillämpliga scenarier:

1. REST är lämplig för:
   • Resursorienterade applikationer (som innehållshanteringssystem, bloggplattformar, e-handelswebbplatser)
   • Scenarier som kräver bra cache-stöd (GET-förfrågningar är naturligt cachelagringsbara)
   • Projekt som vill utnyttja HTTP-syntax (som att använda lämpliga statuskoder)
   • Publika API:er som kräver bra upptäckbarhet och självbeskrivning
2. RPC är lämplig för:
   • Åtgärdsorienterade applikationer (som komplexa databehandlingsoperationer, arbetsflödeskontroll)
   • System som kräver hög prestanda och låg latens (som realtidshandelssystem)
   • Kommunikation mellan interna mikrotjänster (som kan kräva mer flexibel parameterhantering)
   • När operationer inte enkelt kan mappas till CRUD (Create, Read, Update, Delete) operationer

Valet av stil bör baseras på dina specifika behov. I vissa fall kan du till och med använda en blandning av dessa två stilar inom samma system för att tillgodose behoven i olika delar.

Slutsats#

1. Kärnan i API-design ligger i tydlighet, konsekvens, utbyggbarhet och effektivitet, inte i att hålla fast vid en särskild metod eller stil.
2. Både RESTful och RPC är mogna API-design paradigmer. Valet mellan dem bör baseras på projektkrav, inte personliga preferenser.
3. Om du bestämmer dig för att använda "bara POST", designa ditt API enligt RPC-stilen. Liksom RESTful är det en vanligt använd API-specifikation i branschen, men det bör användas i lämpliga scenarier.
4. Låt dig inte förvirras av ytliga tekniska detaljer. Det som verkligen spelar roll är om ditt API effektivt kan tjäna dina användare och affärsbehov.
5. När du designar API:er, lägg mer tid på att tänka på din resursmodell, affärslogik och användarbehov, snarare än att fastna i vilken HTTP-metod du ska använda.

Låt oss flytta vår uppmärksamhet bort från dessa meningslösa argument och fokusera på att designa riktigt utmärkta API:er. Efter allt är teknik till för att lösa problem, inte skapa dem.