Vain POST? Lopetetaan tämä absurdi API-suunnittelukeskustelu

Äskettäin kiinnitin huomiota keskusteluun siitä, pitäisikö API:t suunnitella käyttämällä vain "POST". Tutkittuani tätä väittelyä huomasin, että ei vain ole merkityksetöntä, mistä ihmiset kiistelevät, vaan se myös paljastaa monien kehittäjien väärinymmärryksen API-suunnittelun olemuksesta. Tänään syvennymme API-suunnittelun ydinajatuksiin ja näemme, miksi tätä väittelyä ei pitäisi olla olemassa ensinkään.

"Vain POST" väärinkäsitys#

Kehittäjät, jotka puolustavat "vain POST" -käyttöä korvatakseen RESTful API -määrittelyt, eivät selvästikään ole ymmärtäneet API-suunnittelun tärkeintä kohtaa. Heidän väitteensä sisältävät tavallisesti:

1. Suunnittelun yksinkertaistaminen: Yksi menetelmä voi hoitaa kaiken
2. Turvallisuus: POST-parametrit eivät näy URL-osoitteessa
3. Joustavuus: POST voi lähettää minkä tahansa tietorakenteen

Pintapuolisesti nämä argumentit vaikuttavat järkeviltä. Mutta todellisuudessa tämä näkökanta sekoittaa HTTP-menetelmien valinnan API-suunnittelutyyleihin, jotka ovat kaksi eri tasoista ongelmaa. POST on vain yksi HTTP-protokollan menetelmä, kun taas REST on API-suunnittelutyyli.

API-suunnittelun olemus#

Ennen kuin keskustelemme tietyistä API-tyyleistä, meidän on ymmärrettävä, mikä API-suunnittelun ytimenä on. Hyvä API:n tulisi olla:

1. Selkeä ja ymmärrettävä: Muiden kehittäjien (sisältäen tulevan itsesi) pitäisi pystyä intuitiivisesti ymmärtämään jokaisen päätepisteen tarkoitus
2. Johdonmukainen: Noudata tiettyjä määrittelyjä oppimiskustannusten vähentämiseksi
3. Laajennettavissa: Kyetä helposti suorittamaan versionhallintaa ja toiminnallista laajennusta
4. Tehokas: Harkitse tehokkuutta suorituskyvyn ja resurssien käytön kannalta

RESTful API: Enemmän kuin vain HTTP-menetelmien valinta#

RESTful API on vain yksi monista API-suunnittelutyyleistä, joka keskittyy resursseihin ja resurssien toimintoihin. Otetaanpa yksinkertainen blogijärjestelmä esimerkiksi nähdäksesi, miten RESTful API suunnitellaan:

1. Hanki kaikki artikkelit:

2. Hanki tietty artikkeli:

3. Luo uusi artikkeli:

4. Päivitä artikkeli:

5. Poista artikkeli:

Tässä esimerkissä näemme:

• API on suunniteltu "artikkeli"-resurssin ympärille
• Eri HTTP-menetelmiä käytetään kuvaamaan eri toimintoja
• URL-rakenne on selkeä, osoittaa resurssin, jota operoidaan

Tämä suunnittelutapa tekee API:sta intuitiivisemman ja itseään selittävämmän, mikä helpottaa kehittäjiä ymmärtämään jokaisen päätepisteen toiminnan.

RPC: "Vain POST" -tyylin takana oleva API-tyylin ymmärtäminen#

RPC (Remote Procedure Call) -tyylisen API-suunnittelun tavoitteena on tehdä etäpalvelukutsuista näyttämään yhtä yksinkertaisilta kuin paikallisten funktioiden kutsuminen.

Mielenkiintoista on, että ne, jotka puolustavat "vain POST" -käyttöä, eivät ehkä ymmärrä, että he itse asiassa kuvaavat RPC-tyyliä.

Verrattuna RESTful API:ihin, RPC keskittyy enemmän itse operaatioon kuin resurssiin. Tästä syystä RPC-tyyliset API:t käyttävät yleensä "verbi + substantiivi" -muotoa, kuten getProduct(productId) tai createUser(userData).

Monissa RPC-toteutuksissa kaikki operaatiot lähetetään tavallisesti POST-pyyntöinä samaan päätepisteeseen, jossa tietty toimenpide ja parametrit määritellään pyyntökehossa. Tämä on syy, miksi ajatus "vain POST" on itse asiassa lähempänä RPC: tä kuin REST.

Esimerkiksi RPC-tyylinen "hanki tuote" -pyyntö, joka perustuu HTTP:hen, saattaa näyttää tältä:

Modernit RPC-kehykset, kuten gRPC, tarjoavat tehokkaampia ja tehokkaampia toteutuksia. Käytetään tätä esimerkkiä osoittamaan RPC-tyyliä:

Ensin määritämme palvelun ja viestin muodon (käyttäen Protocol Buffers):

Sitten tämän palvelun käyttäminen Node.js-asiakkaassa on yhtä helppoa kuin paikallisen funktion kutsuminen:

Tässä RPC-tyylisessä esimerkissä näemme:

1. Palvelun määrittely luetteloi selkeästi kaikki saatavilla olevat toiminnot (tässä yksinkertaistetussa esimerkissä GetArticle ja CreateArticle).
2. Jokaisella toiminnolla on selkeästi määritellyt pyyntö- ja vastaustyypit.
3. Asiakaskoodi näyttää paikallisen asynkronisen funktion kutsumiselta, käyttäen await odottamaan tulosta, mikä edelleen piilottaa verkkoviestinnän monimutkaisuuden.
4. Ei tarvitse manuaalisesti rakentaa HTTP-pyyntöjä tai jäsentää JSON-vastauksia.

Vaikka alakerros voi silti käyttää HTTP/2:ta kuljetusprotokollana, RPC-kehykset (kuten gRPC) tarjoavat kehittäjille abstraktiotason, joka saa etäkutsut näyttämään ja tuntumaan paikallisten toimintokutsuilta.

Siksi voimme nähdä, että suurin osa "vain POST" ja RESTful API -väittelyistä pitäisi olennaisesti olla keskusteluja näistä kahdesta API-tyylistä: REST ja RPC. Kuitenkin avain on tunnistaa, että molemmilla tyyleillä on omat soveltamisalueensa ja valinnan tulisi perustua projektin erityistarpeisiin, ei henkilökohtaisiin mieltymyksiin.

REST vs RPC: Ei ole absoluuttista paremmuutta tai huonommuutta#

Nyt kun ymmärrämme erot REST:n ja RPC:n välillä, katsotaanpa niiden soveltuvia skenaarioita:

1. REST sopii:
   • Resurssiorientoituneisiin sovelluksiin (kuten sisällönhallintajärjestelmät, blogialustat, verkkokauppasivustot)
   • Skenaarioihin, jotka edellyttävät hyvää välimuistitukea (GET-pyynnöt ovat luonnostaan välimuistoitavia)
   • Projekteihin, jotka haluavat hyödyntää HTTP-semantikkaa (kuten käyttämällä sopivia tilakoodeja)
   • Julkisille API:eille, jotka vaativat hyvää näkyvyyttä ja itsensä kuvaavuutta
2. RPC sopii:
   • Toimintoorientoituneisiin sovelluksiin (kuten monimutkaiset tietojenkäsittelytoiminnot, työnkulun hallinta)
   • Järjestelmiin, jotka edellyttävät korkeaa suorituskykyä ja matalaa viivettä (kuten reaaliaikaiset kaupankäyntijärjestelmät)
   • Sisäisten mikropalvelujen välillä tapahtuvaan viestintään (joka voi vaatia joustavampaa parametrien välittämistä)
   • Kun toimintoja ei voida yksinkertaisesti kartoittaa CRUD (Luo, Lue, Päivitä, Poista) -toiminnoiksi

Tyylivalinnan tulisi perustua omiin erityistarpeisiisi. Joissain tapauksissa saatat käyttää jopa yhdistelmää näistä kahdesta tyylistä samassa järjestelmässä vastaamaan eri osien tarpeisiin.

Päätelmä#

1. API-suunnittelun ydin on selkeys, johdonmukaisuus, laajennettavuus, ja tehokkuus, ei tietyn menetelmän tai tyylin noudattamisessa.
2. Sekä RESTful että RPC ovat kypsiä API-suunnittelutapoja. Valinta niiden välillä tulisi tehdä projekti vaatimusten perusteella, ei henkilökohtaisen mieltymyksen perusteella.
3. Jos päätät käyttää "vain POST" niin suunnittele API:si RPC-tyylin mukaan. Kuten RESTful, se on yleisesti käytetty API-määrittely teollisuudessa, mutta sitä tulee käyttää sopivissa tilanteissa.
4. Älä anna pinnallisten teknisten yksityiskohtien häiritä. Tärkeintä on se, pystyykö API:si tehokkaasti palvelemaan käyttäjiäsi ja liiketoimintatarpeitasi.
5. Kun suunnittelet API:a, käytä enemmän aikaa resurssimallisi, liiketoimintalogiikkasi ja käyttäjäsi tarpeiden miettimiseen, äläkä murehdi, mitä HTTP-menetelmää käyttää.

Siirretään huomiomme pois näistä turhista väittelyistä ja keskitytään suunnittelemaan todella erinomaisia API:a. Loppujen lopuksi teknologia on tarkoitettu ongelmien ratkaisemiseen, ei niiden luomiseen.