RESTful API disain: parimad praktikad globaalsele publikule

Tänapäeva ühendatud maailmas on API-d (rakendusliidesed) kaasaegse tarkvaraarenduse selgroog. Eelkõige on RESTful API-d saanud veebiteenuste loomise standardiks tänu oma lihtsusele, skaleeritavusele ja koostalitlusvõimele. See juhend pakub põhjalikke parimaid praktikaid RESTful API-de disainimiseks, keskendudes globaalsele kättesaadavusele, hooldatavusele ja turvalisusele.

REST-põhimõtete mõistmine

REST (Representational State Transfer) on arhitektuuristiil, mis määratleb veebiteenuste loomiseks kasutatavate piirangute kogumi. Nende põhimõtete mõistmine on tõhusate RESTful API-de disainimisel ülioluline:

Klient-server: Klient ja server on eraldiseisvad üksused ja võivad areneda iseseisvalt. Klient algatab päringuid ning server töötleb neid ja tagastab vastuseid.
Olekuta (Stateless): Server ei salvesta päringute vahel kliendi olekut. Iga kliendi päring sisaldab kogu teavet, mis on vajalik päringu mõistmiseks ja töötlemiseks. See parandab skaleeritavust ja töökindlust.
Vahemällu salvestatav (Cacheable): Vastused peaksid olema selgelt märgistatud kui vahemällu salvestatavad või mitte. See võimaldab klientidel ja vahendajatel vastuseid vahemällu salvestada, parandades jõudlust ja vähendades serveri koormust.
Kihiline süsteem (Layered System): Klient ei saa tavaliselt aru, kas ta on ühendatud otse lõppserveriga või mõne vahendajaga teel. Vahendajaserverid võivad parandada süsteemi skaleeritavust, võimaldades koormuse jaotamist ja pakkudes jagatud vahemälusid.
Kood nõudmisel (valikuline): Serverid võivad valikuliselt pakkuda klientidele käivitatavat koodi, laiendades kliendi funktsionaalsust. See on vähem levinud, kuid võib teatud stsenaariumide korral kasulik olla.
Ühtne liides (Uniform Interface): See on REST-i põhiprintsiip ja hõlmab mitut alampiirangut:

Ressursside identifitseerimine: Iga ressurss peaks olema tuvastatav unikaalse URI (Uniform Resource Identifier) abil.
Ressursside manipuleerimine esituste kaudu: Kliendid manipuleerivad ressursse, vahetades serveriga esitusi (nt JSON, XML).
Isekirjeldavad sõnumid: Iga sõnum peaks sisaldama piisavalt teavet, et kirjeldada, kuidas sõnumit töödelda. Näiteks näitab päis Content-Type sõnumi keha vormingut.
Hüpermeedia kui rakenduse oleku mootor (HATEOAS): Kliendid peaksid API-s navigeerimiseks kasutama vastuses esitatud hüperlinke. See võimaldab API-l areneda kliente lõhkumata. Kuigi HATEOAS-i ei jõustata alati rangelt, soodustab see lõtva sidusust ja arendatavust.

RESTful ressursside disainimine

Ressursid on RESTful API peamised abstraktsioonid. Need esindavad andmeid, mida API paljastab ja manipuleerib. Siin on mõned parimad praktikad RESTful ressursside disainimiseks:

1. Kasutage nimisõnu, mitte tegusõnu

Ressursid tuleks nimetada nimisõnadega, mitte tegusõnadega. See peegeldab asjaolu, et ressursid on andmeüksused, mitte tegevused. Näiteks kasutage /customers asemel /getCustomers.

Näide:

Selle asemel, et:

/getUser?id=123

Kasutage:

/users/123

2. Kasutage mitmuses nimisõnu

Kasutage ressursikogumike jaoks mitmuses nimisõnu. See edendab järjepidevust ja selgust.

Näide:

Kasutage:

/products

Selle asemel, et:

/product

3. Kasutage hierarhilisi ressursistruktuure

Kasutage ressurssidevaheliste seoste esitamiseks hierarhilisi ressursistruktuure. See muudab API intuitiivsemaks ja lihtsamini navigeeritavaks.

Näide:

/customers/{customer_id}/orders

See esindab konkreetsele kliendile kuuluvate tellimuste kogumit.

4. Hoidke ressursi URI-d lühikesed ja tähendusrikkad

Lühikesi ja tähendusrikkaid URI-sid on lihtsam mõista ja meeles pidada. Vältige pikki ja keerulisi URI-sid, mida on raske parsida.

5. Kasutage järjepidevaid nimetamiskonventsioone

Kehtestage ressurssidele järjepidevad nimetamiskonventsioonid ja pidage neist kogu API ulatuses kinni. See parandab loetavust ja hooldatavust. Kaaluge kogu ettevõtet hõlmava stiilijuhendi kasutamist.

HTTP-meetodid: API tegusõnad

HTTP-meetodid määratlevad tegevused, mida saab ressurssidega teha. Õige HTTP-meetodi kasutamine iga operatsiooni jaoks on RESTful API ehitamisel ülioluline.

GET: Hangib ressursi või ressursikogumi. GET-päringud peaksid olema ohutud (st nad ei tohiks ressurssi muuta) ja idempotentsed (st mitmel identsel päringul peaks olema sama mõju kui ühel päringul).
POST: Loob uue ressursi. POST-päringuid kasutatakse tavaliselt andmete saatmiseks serverile töötlemiseks.
PUT: Uuendab olemasolevat ressurssi. PUT-päringud asendavad kogu ressursi uue esitusega.
PATCH: Uuendab osaliselt olemasolevat ressurssi. PATCH-päringud muudavad ainult ressursi konkreetseid välju.
DELETE: Kustutab ressursi.

Näide:

Uue kliendi loomiseks:

POST /customers

Kliendi hankimiseks:

GET /customers/{customer_id}

Kliendi uuendamiseks:

PUT /customers/{customer_id}

Kliendi osaliseks uuendamiseks:

PATCH /customers/{customer_id}

Kliendi kustutamiseks:

DELETE /customers/{customer_id}

HTTP olekukoodid: tulemuse edastamine

HTTP olekukoode kasutatakse päringu tulemuse edastamiseks kliendile. Õige olekukoodi kasutamine on selge ja informatiivse tagasiside andmiseks hädavajalik.

Siin on mõned kõige levinumad HTTP olekukoodid:

200 OK: Päring oli edukas.
201 Created: Uus ressurss loodi edukalt.
204 No Content: Päring oli edukas, kuid tagastatavat sisu pole.
400 Bad Request: Päring oli vigane. Selle põhjuseks võivad olla puuduvad parameetrid, valed andmed või muud vead.
401 Unauthorized: Klient ei ole volitatud ressursile juurde pääsema. Tavaliselt tähendab see, et klient peab autentima.
403 Forbidden: Klient on autenditud, kuid tal pole luba ressursile juurde pääseda.
404 Not Found: Ressurssi ei leitud.
405 Method Not Allowed: Päringu reas määratud meetod pole päringu URI-ga tuvastatud ressursi jaoks lubatud.
500 Internal Server Error: Serveris ilmnes ootamatu viga.

Näide:

Kui ressurss on edukalt loodud, peaks server tagastama olekukoodi 201 Created koos päisega Location, mis määrab uue ressursi URI.

Andmevormingud: õige esituse valimine

RESTful API-d kasutavad andmete vahetamiseks klientide ja serverite vahel esitusi. JSON (JavaScript Object Notation) on RESTful API-de jaoks kõige populaarsem andmevorming tänu oma lihtsusele, loetavusele ja laialdasele toele programmeerimiskeeltes. XML (Extensible Markup Language) on teine levinud valik, kuid seda peetakse üldiselt sõnaohtramaks ja keerulisemaks kui JSON-i.

Teisi andmevorminguid, nagu Protocol Buffers (protobuf) ja Apache Avro, saab kasutada spetsiifilistel kasutusjuhtudel, kus jõudlus ja andmete serialiseerimise tõhusus on kriitilise tähtsusega.

Parimad praktikad:

Kasutage JSON-i vaikimisi andmevorminguna, kui pole kaalukat põhjust midagi muud kasutada.
Kasutage päist Content-Type, et määrata päringu ja vastuse kehade vorming.
Vajadusel toetage mitut andmevormingut. Kasutage sisu läbirääkimist (päis Accept), et võimaldada klientidel oma eelistatud andmevormingut määrata.

API versioonimine: muutuste haldamine

API-d arenevad aja jooksul. Lisatakse uusi funktsioone, parandatakse vigu ning olemasolevat funktsionaalsust võidakse muuta või eemaldada. API versioonimine on mehhanism nende muutuste haldamiseks olemasolevaid kliente lõhkumata.

API versioonimiseks on mitu levinud lähenemisviisi:

URI versioonimine: Lisage API versioon URI-sse. Näiteks /v1/customers, /v2/customers.
Päise versioonimine: Kasutage API versiooni määramiseks kohandatud HTTP päist. Näiteks X-API-Version: 1.
Meediumitüübi versioonimine: Kasutage API versiooni määramiseks kohandatud meediumitüüpi. Näiteks Accept: application/vnd.example.customer.v1+json.

Parimad praktikad:

Kasutage URI versioonimist kui kõige lihtsamat ja laialdasemalt mõistetavat lähenemisviisi.
Aegunud API versioonid tuleks kasutuselt kõrvaldada järk-järgult. Pakkuge klientidele selget dokumentatsiooni ja migratsioonijuhendeid.
Vältige alati, kui võimalik, rikkumisi põhjustavaid muudatusi. Kui rikkumisi põhjustavad muudatused on vajalikud, tutvustage uut API versiooni.

API turvalisus: oma andmete kaitsmine

API turvalisus on tundlike andmete kaitsmiseks ja volitamata juurdepääsu vältimiseks ülioluline. Siin on mõned parimad praktikad oma RESTful API turvamiseks:

Autentimine: Kontrollige kliendi identiteeti. Levinud autentimismeetodid on järgmised:

Põhiautentimine (Basic Authentication): Lihtne, kuid ebaturvaline. Tuleks kasutada ainult üle HTTPS-i.
API võtmed: Igale kliendile määratud unikaalsed võtmed. Saab kasutada kasutuse jälgimiseks ja päringute piirangute kehtestamiseks.
OAuth 2.0: Standardprotokoll delegeeritud autoriseerimiseks. Võimaldab klientidel pääseda ressurssidele juurde kasutaja nimel, ilma et oleks vaja kasutaja mandaate.
JSON veebimärgid (JWT): Kompaktne ja iseseisev viis teabe turvaliseks edastamiseks osapoolte vahel JSON-objektina.

Autoriseerimine: Kontrollige juurdepääsu ressurssidele vastavalt kliendi identiteedile ja õigustele. Rollipõhine juurdepääsukontroll (RBAC) on levinud lähenemisviis.
HTTPS: Kasutage HTTPS-i kogu suhtluse krüpteerimiseks kliendi ja serveri vahel. See kaitseb andmeid pealtkuulamise ja rikkumise eest.
Sisendi valideerimine: Valideerige kõik sisendandmed, et vältida süstimisrünnakuid ja muid turvaauke.
Päringute piiramine (Rate Limiting): Piirake päringute arvu, mida klient saab teatud aja jooksul teha. See kaitseb API-d kuritarvitamise ja teenusetõkestamise rünnakute eest.
API tulemüür: Kasutage oma API kaitsmiseks levinud rünnakute eest veebirakenduste tulemüüri (WAF) või API lüüsi.

API dokumentatsioon: oma API leitavaks tegemine

Hea API dokumentatsioon on teie API leitavaks ja hõlpsasti kasutatavaks tegemisel hädavajalik. Dokumentatsioon peaks olema selge, lühike ja ajakohane.

Siin on mõned parimad praktikad API dokumentatsiooni jaoks:

Kasutage standardset dokumentatsioonivormingut, nagu OpenAPI Specification (Swagger) või RAML. Need vormingud võimaldavad teil automaatselt genereerida interaktiivset API dokumentatsiooni ja kliendi SDK-sid.
Esitage kõigi ressursside, meetodite ja parameetrite üksikasjalikud kirjeldused.
Lisage koodinäiteid mitmes programmeerimiskeeles.
Esitage selged veateated ja veaotsingu näpunäited.
Hoidke dokumentatsioon uusima API versiooniga ajakohasena.
Pakkuge liivakastikeskkonda, kus arendajad saavad API-d testida, ilma et see mõjutaks tootmisandmeid.

API jõudlus: optimeerimine kiiruse ja skaleeritavuse jaoks

API jõudlus on hea kasutajakogemuse pakkumisel kriitilise tähtsusega. Aeglased API-d võivad viia pettunud kasutajate ja kaotatud äritegevuseni.

Siin on mõned parimad praktikad API jõudluse optimeerimiseks:

Kasutage vahemälu andmebaasi koormuse vähendamiseks. Salvestage sageli kasutatavad andmed mällu või hajutatud vahemällu.
Optimeerige andmebaasi päringuid. Kasutage indekseid, vältige täielikke tabeliskaneeringuid ja kasutage tõhusaid päringukeeli.
Kasutage ühenduste koondamist (connection pooling), et vähendada andmebaasi ühenduse loomise kulusid.
Tihendage vastuseid, kasutades gzipi või muid tihendusalgoritme.
Kasutage sisuedastusvõrku (CDN), et salvestada staatilist sisu kasutajatele lähemale.
Jälgige API jõudlust tööriistadega nagu New Relic, Datadog või Prometheus.
Profileerige oma koodi, et tuvastada jõudluse kitsaskohti.
Kaaluge asünkroonse töötlemise kasutamist pikaajaliste ülesannete jaoks.

API rahvusvahelistamine (i18n) ja lokaliseerimine (l10n)

Globaalsele publikule mõeldud API-de disainimisel arvestage rahvusvahelistamise (i18n) ja lokaliseerimisega (l10n). See hõlmab oma API disainimist nii, et see toetaks mitut keelt, valuutat ja kuupäeva/kellaaja vormingut.

Parimad praktikad:

Kasutage kogu tekstiandmete jaoks Unicode (UTF-8) kodeeringut.
Salvestage kogu tekst neutraalses keeles (nt inglise keeles) ja pakkuge tõlkeid teistesse keeltesse.
Kasutage päist Accept-Language, et määrata kasutaja eelistatud keel.
Kasutage päist Accept-Charset, et määrata kasutaja eelistatud märgistik.
Kasutage päist Accept, et määrata kasutaja eelistatud sisuvorming.
Toetage mitut valuutat ja kasutage ISO 4217 valuutakoodi standardit.
Toetage mitut kuupäeva/kellaaja vormingut ja kasutage ISO 8601 kuupäeva/kellaaja vormingu standardit.
Arvestage kultuuriliste erinevuste mõjuga API disainile. Näiteks võivad mõned kultuurid eelistada erinevaid kuupäeva/kellaaja või numbrite vorminguid.

Näide:

Globaalne e-kaubanduse API võib toetada mitut valuutat (USD, EUR, JPY) ja lubada kasutajatel oma eelistatud valuutat määrata päringu parameetri või päise abil.

GET /products?currency=EUR

API seire ja analüütika

Oma API jõudluse, kasutuse ja vigade jälgimine on selle tervise ja stabiilsuse tagamiseks ülioluline. API analüütika annab väärtuslikku teavet selle kohta, kuidas teie API-d kasutatakse, ja aitab teil tuvastada parendusvaldkondi.

Põhilised jälgitavad mõõdikud:

Vastuse aeg: Keskmine aeg, mis kulub API-l päringule vastamiseks.
Vigade määr: Veaga lõppevate päringute protsent.
Päringute maht: Päringute arv ajaühikus.
Kasutusmustrid: Milliseid API lõpp-punkte kasutatakse kõige rohkem? Kes on peamised kasutajad?
Ressursside kasutus: API serverite protsessori, mälu ja võrgu kasutus.

Tööriistad API seireks ja analüütikaks:

New Relic
Datadog
Prometheus
Amazon CloudWatch
Google Cloud Monitoring
Azure Monitor

Kokkuvõte

RESTful API disainimine globaalsele publikule nõuab mitmete tegurite hoolikat kaalumist, sealhulgas REST-põhimõtted, ressursidisain, HTTP-meetodid ja olekukoodid, andmevormingud, API versioonimine, turvalisus, dokumentatsioon, jõudlus, rahvusvahelistamine ja seire. Selles juhendis kirjeldatud parimaid praktikaid järgides saate luua API-sid, mis on skaleeritavad, hooldatavad, turvalised ja kättesaadavad arendajatele üle kogu maailma. Pidage meeles, et API disain on iteratiivne protsess. Jälgige pidevalt oma API-d, koguge kasutajatelt tagasisidet ja kohandage oma disaini vastavalt arenevatele vajadustele.