RESTful API projektavimas: geriausios praktikos pasaulinei auditorijai

Šiuolaikiniame susietame pasaulyje API (aplikacijų programavimo sąsajos) yra šiuolaikinės programinės įrangos kūrimo pagrindas. Ypač RESTful API tapo standartu kuriant žiniatinklio paslaugas dėl savo paprastumo, mastelio keitimo galimybių ir sąveikumo. Šiame vadove pateikiamos išsamios geriausios praktikos, skirtos RESTful API projektavimui, daugiausia dėmesio skiriant pasauliniam prieinamumui, palaikomumui ir saugumui.

REST principų supratimas

REST (Representational State Transfer) yra architektūrinis stilius, apibrėžiantis apribojimų rinkinį, kuris naudojamas kuriant žiniatinklio paslaugas. Šių principų supratimas yra labai svarbus kuriant efektyvias RESTful API:

• Klientas-serveris: Klientas ir serveris yra atskiri subjektai ir gali vystytis nepriklausomai. Klientas inicijuoja užklausas, o serveris jas apdoroja ir grąžina atsakymus.
• Besąlyginis (Stateless): Serveris nesaugo jokios kliento būsenos tarp užklausų. Kiekvienoje kliento užklausoje yra visa informacija, reikalinga užklausai suprasti ir apdoroti. Tai pagerina mastelio keitimą ir patikimumą.
• Kešuojamas (Cacheable): Atsakymai turėtų būti aiškiai pažymėti kaip kešuojami arba nekešuojami. Tai leidžia klientams ir tarpininkams kešuoti atsakymus, gerinant našumą ir mažinant serverio apkrovą.
• Sluoksniuota sistema: Klientas paprastai negali pasakyti, ar jis yra tiesiogiai prijungtas prie galutinio serverio, ar prie tarpininko. Tarpiniai serveriai gali pagerinti sistemos mastelio keitimą, įgalindami apkrovos balansavimą ir teikdami bendras podėlius (caches).
• Kodas pagal pareikalavimą (neprivaloma): Serveriai gali pasirinktinai teikti vykdomąjį kodą klientams, praplečiant kliento funkcionalumą. Tai yra mažiau paplitę, bet gali būti naudinga tam tikrais atvejais.
• Vienoda sąsaja: Tai yra pagrindinis REST principas, apimantis kelis papildomus apribojimus:
• Išteklių identifikavimas: Kiekvienas išteklius turėtų būti identifikuojamas naudojant unikalų URI (Uniform Resource Identifier).
• Išteklių manipuliavimas per reprezentacijas: Klientai manipuliuoja ištekliais keisdamiesi reprezentacijomis (pvz., JSON, XML) su serveriu.
• Savaime aprašantys pranešimai: Kiekviename pranešime turėtų būti pakankamai informacijos, kad būtų galima aprašyti, kaip apdoroti pranešimą. Pavyzdžiui, „Content-Type“ antraštė nurodo pranešimo turinio formatą.
• Hipermedija kaip programos būsenos variklis (HATEOAS): Klientai turėtų naudoti atsakyme pateiktas hipersaitus, kad naršytų API. Tai leidžia API vystytis nepažeidžiant klientų. Nors HATEOAS ne visada griežtai laikomasi, jis skatina laisvą susiejimą ir evoliuciją.

RESTful išteklių projektavimas

Ištekliai yra pagrindinės abstrakcijos RESTful API. Jie reprezentuoja duomenis, kuriuos API atveria ir manipuliuoja. Štai keletas geriausių praktikų, kaip projektuoti RESTful išteklius:

1. Naudokite daiktavardžius, o ne veiksmažodžius

Ištekliai turėtų būti pavadinti daiktavardžiais, o ne veiksmažodžiais. Tai atspindi faktą, kad ištekliai yra duomenų subjektai, o ne veiksmai. Pavyzdžiui, naudokite /customers vietoj /getCustomers.

Pavyzdys:

Vietoj:

            /getUser?id=123
            

              
                Copy
              
            
          

Naudokite:

            /users/123
            

              
                Copy
              
            
          

2. Naudokite daugiskaitos daiktavardžius

Naudokite daugiskaitos daiktavardžius išteklių rinkiniams. Tai skatina nuoseklumą ir aiškumą.

Pavyzdys:

Naudokite:

            /products
            

              
                Copy
              
            
          

Vietoj:

            /product
            

              
                Copy
              
            
          

3. Naudokite hierarchines išteklių struktūras

Naudokite hierarchines išteklių struktūras, kad atspindėtumėte ryšius tarp išteklių. Tai daro API intuityvesnę ir lengviau naršomą.

Pavyzdys:

            /customers/{customer_id}/orders
            

              
                Copy
              
            
          

Tai reprezentuoja tam tikro kliento užsakymų rinkinį.

4. Laikykite išteklių URI trumpus ir prasmingus

Trumpus ir prasmingus URI yra lengviau suprasti ir įsiminti. Venkite ilgų, sudėtingų URI, kuriuos sunku analizuoti.

5. Naudokite nuoseklias pavadinimų taisykles

Nustatykite nuoseklias pavadinimų taisykles ištekliams ir laikykitės jų visoje API. Tai pagerina skaitomumą ir palaikomumą. Apsvarstykite galimybę naudoti visos įmonės stiliaus vadovą.

HTTP metodai: API veiksmažodžiai

HTTP metodai apibrėžia veiksmus, kuriuos galima atlikti su ištekliais. Teisingo HTTP metodo naudojimas kiekvienai operacijai yra labai svarbus kuriant RESTful API.

• GET: Nuskaito išteklių ar išteklių rinkinį. GET užklausos turėtų būti saugios (t. y. jos neturėtų keisti ištekliaus) ir idempotentinės (t. y. kelios identiškos užklausos turėtų turėti tokį patį poveikį kaip viena užklausa).
• POST: Sukuria naują išteklių. POST užklausos paprastai naudojamos duomenims pateikti serveriui apdoroti.
• PUT: Atnaujina esamą išteklių. PUT užklausos pakeičia visą išteklių nauja reprezentacija.
• PATCH: Dalinai atnaujina esamą išteklių. PATCH užklausos keičia tik konkrečius ištekliaus laukus.
• DELETE: Ištrina išteklių.

Pavyzdys:

Norėdami sukurti naują klientą:

            POST /customers
            

              
                Copy
              
            
          

Norėdami gauti klientą:

            GET /customers/{customer_id}
            

              
                Copy
              
            
          

Norėdami atnaujinti klientą:

            PUT /customers/{customer_id}
            

              
                Copy
              
            
          

Norėdami dalinai atnaujinti klientą:

            PATCH /customers/{customer_id}
            

              
                Copy
              
            
          

Norėdami ištrinti klientą:

            DELETE /customers/{customer_id}
            

              
                Copy
              
            
          

HTTP būsenos kodai: rezultato komunikavimas

HTTP būsenos kodai naudojami norint pranešti klientui apie užklausos rezultatą. Teisingo būsenos kodo naudojimas yra būtinas norint pateikti aiškų ir informatyvų grįžtamąjį ryšį.

Štai keletas dažniausiai naudojamų HTTP būsenos kodų:

• 200 OK: Užklausa buvo sėkminga.
• 201 Created: Naujas išteklius buvo sėkmingai sukurtas.
• 204 No Content: Užklausa buvo sėkminga, bet nėra turinio, kurį būtų galima grąžinti.
• 400 Bad Request: Užklausa buvo neteisinga. Taip galėjo nutikti dėl trūkstamų parametrų, neteisingų duomenų ar kitų klaidų.
• 401 Unauthorized: Klientas neturi teisės pasiekti ištekliaus. Tai paprastai reiškia, kad klientas turi autentifikuotis.
• 403 Forbidden: Klientas yra autentifikuotas, bet neturi leidimo pasiekti ištekliaus.
• 404 Not Found: Išteklius nerastas.
• 405 Method Not Allowed: Užklausos eilutėje nurodytas metodas neleidžiamas ištekliui, identifikuotam pagal užklausos URI.
• 500 Internal Server Error: Serveryje įvyko netikėta klaida.

Pavyzdys:

Jei išteklius sėkmingai sukurtas, serveris turėtų grąžinti 201 Created būsenos kodą kartu su Location antrašte, kuri nurodo naujo ištekliaus URI.

Duomenų formatai: tinkamos reprezentacijos pasirinkimas

RESTful API naudoja reprezentacijas duomenims keistis tarp klientų ir serverių. JSON (JavaScript Object Notation) yra populiariausias duomenų formatas RESTful API dėl savo paprastumo, skaitomumo ir plataus palaikymo įvairiose programavimo kalbose. XML (Extensible Markup Language) yra kita dažna parinktis, tačiau ji paprastai laikoma išsamesne ir sudėtingesne nei JSON.

Kiti duomenų formatai, tokie kaip Protocol Buffers (protobuf) ir Apache Avro, gali būti naudojami specifiniais atvejais, kai našumas ir duomenų serializavimo efektyvumas yra kritiškai svarbūs.

Geriausios praktikos:

• Naudokite JSON kaip numatytąjį duomenų formatą, nebent yra svari priežastis naudoti ką nors kita.
• Naudokite Content-Type antraštę, kad nurodytumėte užklausos ir atsakymo turinio formatą.
• Palaikykite kelis duomenų formatus, jei reikia. Naudokite turinio derinimą (Accept antraštę), kad leistumėte klientams nurodyti pageidaujamą duomenų formatą.

API versijavimas: pokyčių valdymas

API laikui bėgant vystosi. Pridedamos naujos funkcijos, taisomos klaidos, o esamas funkcionalumas gali būti pakeistas arba pašalintas. API versijavimas yra mechanizmas, skirtas valdyti šiuos pokyčius nepažeidžiant esamų klientų.

Yra keletas įprastų API versijavimo būdų:

• Versijavimas per URI: Įtraukite API versiją į URI. Pavyzdžiui, /v1/customers, /v2/customers.
• Versijavimas per antraštę: Naudokite pasirinktinę HTTP antraštę, kad nurodytumėte API versiją. Pavyzdžiui, X-API-Version: 1.
• Versijavimas per medijos tipą: Naudokite pasirinktinį medijos tipą, kad nurodytumėte API versiją. Pavyzdžiui, Accept: application/vnd.example.customer.v1+json.

Geriausios praktikos:

• Naudokite versijavimą per URI kaip paprasčiausią ir plačiausiai suprantamą būdą.
• Palaipsniui nustokite palaikyti senas API versijas. Pateikite aiškią dokumentaciją ir migracijos vadovus klientams.
• Kiek įmanoma, venkite pakeitimų, kurie pažeistų suderinamumą. Jei tokie pakeitimai yra būtini, įveskite naują API versiją.

API saugumas: jūsų duomenų apsauga

API saugumas yra kritiškai svarbus norint apsaugoti jautrius duomenis ir užkirsti kelią neteisėtai prieigai. Štai keletas geriausių praktikų, kaip apsaugoti jūsų RESTful API:

• Autentifikacija: Patikrinkite kliento tapatybę. Įprasti autentifikavimo metodai apima:
• Bazinė autentifikacija: Paprasta, bet nesaugi. Turėtų būti naudojama tik per HTTPS.
• API raktai: Unikalūs raktai, priskirti kiekvienam klientui. Gali būti naudojami naudojimo stebėjimui ir užklausų limitų taikymui.
• OAuth 2.0: Standartinis protokolas deleguotai autorizacijai. Leidžia klientams pasiekti išteklius vartotojo vardu, nereikalaujant vartotojo prisijungimo duomenų.
• JSON Web Tokens (JWT): Kompaktiškas ir savarankiškas būdas saugiai perduoti informaciją tarp šalių kaip JSON objektą.
• Autorizacija: Kontroliuokite prieigą prie išteklių atsižvelgiant į kliento tapatybę ir leidimus. Vaidmenimis pagrįsta prieigos kontrolė (RBAC) yra įprastas metodas.
• HTTPS: Naudokite HTTPS visam ryšiui tarp kliento ir serverio šifruoti. Tai apsaugo duomenis nuo pasiklausymo ir klastojimo.
• Įvesties patvirtinimas: Patvirtinkite visus įvesties duomenis, kad išvengtumėte injekcijos atakų ir kitų saugumo pažeidžiamumų.
• Užklausų limitavimas: Apribokite užklausų, kurias klientas gali pateikti per tam tikrą laikotarpį, skaičių. Tai apsaugo API nuo piktnaudžiavimo ir paslaugos trikdymo (denial-of-service) atakų.
• API užkarda: Naudokite žiniatinklio programų užkardą (WAF) arba API šliuzą (Gateway), kad apsaugotumėte savo API nuo įprastų atakų.

API dokumentacija: kaip padaryti jūsų API atrandamą

Gera API dokumentacija yra būtina, kad jūsų API būtų atrandama ir lengvai naudojama. Dokumentacija turėtų būti aiški, glausta ir naujausia.

Štai keletas geriausių praktikų API dokumentacijai:

• Naudokite standartinį dokumentacijos formatą, pvz., OpenAPI Specification (Swagger) arba RAML. Šie formatai leidžia automatiškai generuoti interaktyvią API dokumentaciją ir kliento SDK.
• Pateikite išsamius visų išteklių, metodų ir parametrų aprašymus.
• Įtraukite kodo pavyzdžių keliomis programavimo kalbomis.
• Pateikite aiškius klaidų pranešimus ir trikčių šalinimo patarimus.
• Laikykite dokumentaciją atnaujintą pagal naujausią API versiją.
• Pasiūlykite „smėlio dėžės“ (sandbox) aplinką, kurioje kūrėjai galėtų išbandyti API nepaveikdami gamybinių duomenų.

API našumas: optimizavimas greičiui ir mastelio keitimui

API našumas yra labai svarbus siekiant užtikrinti gerą vartotojo patirtį. Lėtos API gali sukelti nusivylusius vartotojus ir prarastą verslą.

Štai keletas geriausių praktikų API našumui optimizuoti:

• Naudokite kešavimą, kad sumažintumėte duomenų bazės apkrovą. Kešuokite dažnai pasiekiamus duomenis atmintyje arba paskirstytame keše.
• Optimizuokite duomenų bazės užklausas. Naudokite indeksus, venkite pilnų lentelių nuskaitymo ir naudokite efektyvias užklausų kalbas.
• Naudokite jungčių telkimą (connection pooling), kad sumažintumėte duomenų bazės jungčių pridėtines išlaidas.
• Suspauskite atsakymus naudodami gzip ar kitus suspaudimo algoritmus.
• Naudokite turinio pristatymo tinklą (CDN), kad statinis turinys būtų kešuojamas arčiau vartotojų.
• Stebėkite API našumą naudodami įrankius, tokius kaip New Relic, Datadog ar Prometheus.
• Profiluokite savo kodą, kad nustatytumėte našumo kliūtis.
• Apsvarstykite galimybę naudoti asinchroninį apdorojimą ilgai trunkančioms užduotims.

API internacionalizacija (i18n) ir lokalizacija (l10n)

Projektuojant API pasaulinei auditorijai, apsvarstykite internacionalizaciją (i18n) ir lokalizaciją (l10n). Tai apima jūsų API projektavimą, kad būtų palaikomos kelios kalbos, valiutos ir datos/laiko formatai.

Geriausios praktikos:

• Visam tekstui naudokite Unicode (UTF-8) koduotę.
• Visą tekstą saugokite neutralia kalba (pvz., anglų) ir pateikite vertimus į kitas kalbas.
• Naudokite Accept-Language antraštę, kad nustatytumėte vartotojo pageidaujamą kalbą.
• Naudokite Accept-Charset antraštę, kad nustatytumėte vartotojo pageidaujamą simbolių rinkinį.
• Naudokite Accept antraštę, kad nustatytumėte vartotojo pageidaujamą turinio formatą.
• Palaikykite kelias valiutas ir naudokite ISO 4217 valiutų kodų standartą.
• Palaikykite kelis datos/laiko formatus ir naudokite ISO 8601 datos/laiko formato standartą.
• Apsvarstykite kultūrinių skirtumų poveikį API projektavimui. Pavyzdžiui, kai kuriose kultūrose gali būti pageidaujami skirtingi datos/laiko ar skaičių formatai.

Pavyzdys:

Pasaulinė e. komercijos API gali palaikyti kelias valiutas (USD, EUR, JPY) ir leisti vartotojams nurodyti pageidaujamą valiutą naudojant užklausos parametrą ar antraštę.

            GET /products?currency=EUR
            

              
                Copy
              
            
          

API stebėjimas ir analizė

Jūsų API našumo, naudojimo ir klaidų stebėjimas yra labai svarbus siekiant užtikrinti jos būklę ir stabilumą. API analizė suteikia vertingų įžvalgų apie tai, kaip jūsų API yra naudojama, ir gali padėti jums nustatyti tobulintinas sritis.

Pagrindiniai stebimi rodikliai:

• Atsakymo laikas: Vidutinis laikas, per kurį API atsako į užklausą.
• Klaidų dažnis: Užklausų, kurios baigiasi klaida, procentas.
• Užklausų apimtis: Užklausų skaičius per laiko vienetą.
• Naudojimo modeliai: Kurie API galiniai taškai (endpoints) yra naudojami dažniausiai? Kas yra aktyviausi vartotojai?
• Išteklių naudojimas: API serverių procesoriaus, atminties ir tinklo naudojimas.

Įrankiai API stebėjimui ir analizei:

• New Relic
• Datadog
• Prometheus
• Amazon CloudWatch
• Google Cloud Monitoring
• Azure Monitor

Išvada

Projektuojant RESTful API pasaulinei auditorijai reikia atidžiai apsvarstyti kelis veiksnius, įskaitant REST principus, išteklių projektavimą, HTTP metodus ir būsenos kodus, duomenų formatus, API versijavimą, saugumą, dokumentaciją, našumą, internacionalizaciją ir stebėjimą. Laikydamiesi šiame vadove pateiktų geriausių praktikų, galite sukurti API, kurios yra mastelio keičiamos, palaikomos, saugios ir prieinamos kūrėjams visame pasaulyje. Atminkite, kad API projektavimas yra iteracinis procesas. Nuolat stebėkite savo API, rinkite grįžtamąjį ryšį iš vartotojų ir prireikus pritaikykite savo dizainą, kad atitiktumėte kintančius poreikius.