10 paraugprakse Node.js REST API rakstīšanai

Šajā rakstā mēs aplūkojam paraugpraksi Node.js REST API rakstīšanai, ieskaitot tādas tēmas kā maršrutu nosaukšana, autentifikācija, melnās kastes pārbaude un šo resursu pareiza kešatmiņas galvenes izmantošana.

Viens no populārākajiem Node.js lietošanas gadījumiem ir RESTful API rakstīšana, izmantojot to. Tomēr, lai gan mēs palīdzam klientiem atrast problēmas viņu lietojumprogrammās ar Trace, mūsu Node.js uzraudzības rīku, mēs pastāvīgi pieredzam, ka izstrādātājiem ir daudz problēmu ar REST API.

Es ceru, ka šī labākā prakse, kuru mēs izmantojam vietnē RisingStack, var palīdzēt:

# 1: izmantojiet HTTP metodes un API maršrutus

Iedomājieties, ka jūs veidojat Node.js RESTful API lietotāju izveidošanai, atjaunināšanai, izguvei vai dzēšanai. Šīm operācijām HTTP jau ir atbilstošs rīku komplekts: POST, PUT, GET, PATCH vai DELETE.

Kā paraugprakse jūsu API maršrutos kā resursa identifikatoros vienmēr jāizmanto lietvārdi. Runājot par lietotāja resursiem, maršrutēšana var izskatīties šādi:

  • POST / user vai PUT / user: / id, lai izveidotu jaunu lietotāju,
  • GET / user iegūt lietotāju sarakstu,
  • GET / user /: id, lai iegūtu lietotāju,
  • PATCH / user /: id, lai modificētu esošo lietotāja ierakstu,
  • DELETE / user /: id, lai noņemtu lietotāju.

# 2: Pareizi izmantojiet HTTP statusa kodus

Ja pieprasījuma apstrādes laikā kaut kas noiet greizi, atbildē jāiestata tam pareizais statusa kods:

  • 2xx, ja viss bija kārtībā,
  • 3xx, ja resurss tika pārvietots,
  • 4xx, ja pieprasījumu nevar izpildīt klienta kļūdas dēļ (piemēram, pieprasīt resursu, kas neeksistē),
  • 5xx, ja API pusē kaut kas neizdevās (piemēram, notika izņēmums).

Ja izmantojat Express, statusa koda iestatīšana ir tikpat vienkārša kā res.status (500) .send ({kļūda: 'Notika iekšējā servera kļūda'}). Līdzīgi kā ar Restify: res.status (201).

Pilnu sarakstu skatiet HTTP statusa kodu sarakstā

# 3: izmantojiet HTTP galvenes, lai nosūtītu metadatus

Lai pievienotu metadatus par nosūtāmo kravas daudzumu, izmantojiet HTTP galvenes. Šādas galvenes var būt informācija par:

  • lapaspuse,
  • likmes ierobežošana,
  • vai autentifikācija.

Standartizētu HTTP galvenes sarakstu var atrast šeit.

Ja jums galvenēs bija jāiestata pielāgoti metadati, vislabākā prakse bija tos pievienot ar X. Piemēram, ja jūs izmantojāt CSRF pilnvaras, tas bija parasts (bet nestandarta) veids, kā tos nosaukt par X-Csrf. -Padomā. Tomēr ar RFC 6648 viņi novecoja. Jaunajām API būtu jāpieliek visas pūles, lai neizmantotu galvenes nosaukumus, kas var būt pretrunā ar citām lietojumprogrammām. Piemēram, OpenStack prefiksē galvenes, izmantojot OpenStack:

OpenStack-Identity-Account-ID
OpenStack-Networking-Host-Name
OpenStack-Object-Storage-Policy

Ņemiet vērā, ka HTTP standarts nenosaka virsrakstu lieluma ierobežojumus; tomēr Node.js (sākot ar šī raksta rakstīšanu) praktisku apsvērumu dēļ galvenes objektam nosaka 80KB lieluma ierobežojumu.

“Neļaujiet kopējam HTTP galvenes lielumam (ieskaitot statusa rindu) pārsniegt HTTP_MAX_HEADER_SIZE. Šī pārbaude ir paredzēta, lai aizsargātu iegultus no pakalpojumu liegšanas uzbrukumiem, ja uzbrucējs mums padod nebeidzamu galveni, kuru iegultnis turpina buferizēt. "
No Node.js HTTP parsētāja

# 4: izvēlieties pareizo sava Node.js REST API ietvaru

Ir svarīgi izvēlēties ietvaru, kas ir vispiemērotākais jūsu lietojuma gadījumam.

Express, Koa vai Hapi

Express, Koa un Hapi var izmantot, lai izveidotu pārlūka lietojumprogrammas, un kā tādas tās atbalsta veidņu veidošanu un atveidošanu - lai tikai nosauktu dažas funkcijas. Ja jūsu lietojumprogrammai ir jānodrošina arī lietotājam vērsta puse, ir jēga tos meklēt.

Atjaunojies

No otras puses, Restify koncentrējas uz to, lai palīdzētu jums veidot REST pakalpojumus. Tas ļauj jums izveidot “stingrus” API pakalpojumus, kas ir uzturējami un novērojami. Restify nāk arī ar automātisku DTrace atbalstu visiem jūsu apstrādātājiem.

Restify tiek izmantots ražošanā lielākās lietojumprogrammās, piemēram, npm vai Netflix.

# 5: Black-Box Pārbaudiet savas Node.js REST API

Viens no labākajiem REST API testēšanas veidiem ir izturēšanās pret tām kā melnajām kastēm.

Melnās kastes pārbaude ir testēšanas metode, kurā lietojumprogrammas funkcionalitāte tiek pārbaudīta, nezinot par tās iekšējām struktūrām vai darbību. Tātad neviena no atkarībām netiek ņirgājusies vai apmētāta, bet sistēma tiek pārbaudīta kopumā.

Viens no moduļiem, kas var jums palīdzēt, pārbaudot Node.js REST API melnās kastes pārbaudi, ir visiecienītākais.

Vienkāršu testa gadījumu, kurā tiek pārbaudīts, vai lietotājs tiek atgriezts atpakaļ, izmantojot testa skrējēja moku, var īstenot šādi:

const pieprasījums = pieprasīt ('supertest')
 
aprakstīt ('GET / user /: id', function () {
  tas ('atdod lietotāju', funkcija () {
    // Jaunākas mokas versijas pieņem arī solījumus
    atgriešanās pieprasījums (lietotne)
      .get ('/ lietotājs')
      .set ('Pieņemt', 'pieteikums / json')
      . gaidīt (200, {
        id: “1”,
        nosaukums: 'John Math'
      }, pabeigts)
  })
})

Var jautāt: kā dati tiek ievadīti datu bāzē, kas kalpo REST API?

Parasti tā ir laba pieeja, lai uzrakstītu testus tā, lai tie izdarītu pēc iespējas mazāk pieņēmumu par sistēmas stāvokli. Tomēr dažos gadījumos jūs varat nonākt situācijā, kad jums precīzi jāzina, kāds ir sistēmas stāvoklis, lai jūs varētu izteikt apgalvojumus un sasniegt augstāku testa pārklājumu.

Tātad, pamatojoties uz jūsu vajadzībām, datubāzi var aizpildīt ar testa datiem vienā no šiem veidiem:

  • izpildiet melnās kastes testa scenārijus zināmā ražošanas datu apakškopā,
  • pirms testa gadījumu izpildes aizpildiet datu bāzi ar izstrādātiem datiem.

Protams, melnās kastes pārbaude nenozīmē, ka jums nav jāveic vienības pārbaude, jums joprojām ir jāraksta vienību testi jūsu API.

# 6: veiciet bezkontaktu autentifikāciju, pamatojoties uz JWT

Tā kā jūsu REST API ir jābūt bezvalstniekam, tāpat kā jūsu autentifikācijas slānim. Šim nolūkam ir ideāls JWT (JSON Web Token).

JWT sastāv no trim daļām:

  • Header, kurā ir marķiera tips un sajaukšanas algoritms
  • Krava ar pretenzijām
  • Paraksts (JWT neveic šifrēšanu ar derīgo kravu, bet tikai to paraksta!)

JWT balstītas autentifikācijas pievienošana jūsu lietojumprogrammai ir ļoti vienkārša:

const koa = prasīt ('koa')
const jwt = prasīt ('koa-jwt')
const app = koa ()
app.use (jwt ({
  slepens: “ļoti slepens”
}))
// Aizsargāta starpprogrammatūra
app.use (funkcija * () {
  // marķiera saturs būs pieejams šajā.state.user
  this.body = {
    noslēpums: “42”
  }
})

Pēc tam API galapunkti tiek aizsargāti ar JWT. Lai piekļūtu aizsargātajiem parametriem, laukā Atļauja galvenes ir jānorāda pilnvara.

curl - header "Autorizācija: nesējs eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwI
iwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30
RMHrHDcEfxjoYZgeFONFh7HgQ "mana vietne.com

Viena lieta, ko jūs varētu pamanīt, ir tas, ka JWT modulis nav atkarīgs no jebkura datu bāzes slāņa. Tas tā ir tāpēc, ka visus JWT pilnvaras var pārbaudīt patstāvīgi, un tajās var būt arī laiks dzīvot vērtībām.

Jums vienmēr jāpārliecinās, vai visi jūsu API galapunkti ir pieejami tikai caur drošu savienojumu, izmantojot HTTPS.

Iepriekšējā rakstā mēs sīki izskaidrojām tīmekļa autentifikācijas metodes - iesaku to pārbaudīt!

# 7: izmantojiet nosacītos pieprasījumus

Nosacīti pieprasījumi ir HTTP pieprasījumi, kas tiek izpildīti atšķirīgi atkarībā no konkrētām HTTP galvenēm. Šīs galvenes var uzskatīt par priekšnoteikumiem: ja tās tiek izpildītas, pieprasījumi tiks izpildīti citādā veidā.

Šīs galvenes mēģina pārbaudīt, vai serverī saglabātā resursa versija atbilst tā paša resursa dotajai versijai. Šī iemesla dēļ šīs galvenes var būt:

  • pēdējās modifikācijas laika zīmogs,
  • vai entītijas tagu, kas katrai versijai ir atšķirīgs.

Šīs galvenes ir:

  • Pēdējoreiz modificēts (lai norādītu, kad resurss pēdējoreiz modificēts),
  • Etag (lai norādītu entītijas tagu),
  • Ja modificēts kopš tā laika (tiek izmantots ar pēdējoreiz modificēto galveni),
  • Ja nav-atbilst (izmanto kopā ar Etag galveni),

Apskatīsim piemēru!

Zemāk esošajam klientam nebija iepriekšējo doc resursa versiju, tāpēc resursa nosūtīšanas laikā netika piemērota ne galvenne If-Modified-Since un If-None-Match. Pēc tam serveris atbild ar pareizi iestatītām galvenēm Etag un Last-Modified.

No MDN nosacītā pieprasījuma dokumentācijas

Tiklīdz klients mēģina pieprasīt to pašu resursu, klients var iestatīt galvenes If-Modified-Since un If-None-Match. Tā kā tam ir versija tagad. Ja atbilde būtu tāda pati, serveris vienkārši atbild ar statusu 304 - Nav modificēts un resursu vairs nenosūta.

No MDN nosacītā pieprasījuma dokumentācijas

# 8: Apskāvienu skaita ierobežošana

Likmes ierobežošana tiek izmantota, lai kontrolētu, cik pieprasījumu konkrēts patērētājs var nosūtīt API.

Lai pastāstītu API lietotājiem, cik daudz pieprasījumu viņiem ir atlicis, iestatiet šādas galvenes:

  • X-Rate-Limit-Limit - atļauto pieprasījumu skaits noteiktā laika intervālā
  • X-Rate-Limit-Remaining - pieprasījumu skaits, kas paliek tajā pašā intervālā,
  • X-Rate-Limit-Reset - laiks, kad tiks atiestatīts likmes ierobežojums.

Lielākā daļa HTTP ietvaru atbalsta to ārpus karkasa (vai ar spraudņiem). Piemēram, ja jūs izmantojat Koa, tur ir koa-ratelimit pakotne.

Ņemiet vērā, ka laika logs var atšķirties atkarībā no dažādiem API nodrošinātājiem - piemēram, GitHub tam izmanto stundu, bet Twitter 15 minūtes.

# 9: izveidojiet pareizu API dokumentāciju

Jūs rakstāt API, lai citi varētu tos izmantot, lai no tiem gūtu labumu. Ir ļoti svarīgi nodrošināt API dokumentāciju jūsu Node.js REST API.

Šādi atvērtā pirmkoda projekti var jums palīdzēt izveidot API jūsu dokumentāciju:

  • API projekts
  • Swagger

Alternatīvi, ja vēlaties izmantot mitinātus produktus, varat meklēt dravu.

# 10: Nepalaidiet garām API nākotni

Iepriekšējos gados radās divas galvenās API vaicājumu valodas - proti, GraphQL no Facebook un Falcor no Netflix. Bet kāpēc mums viņi pat ir vajadzīgi?

Iedomājieties šādu RESTful resursu pieprasījumu:

/ org / 1 / telpa / 2 / docs / 1 / līdzstrādnieki?
ietvert = e-pasts un lapa = 1 un ierobežojums = 10

Tas diezgan viegli var izkļūt no rokas - tā kā jūs visu laiku vēlaties saņemt vienādu atbildes formātu visiem saviem modeļiem. Šeit var palīdzēt GraphQL un Falcor.

Par GraphQL

GraphQL ir API vaicājumu valoda un izpildlaiks šo vaicājumu izpildei ar jūsu esošajiem datiem. GraphQL nodrošina pilnīgu un saprotamu jūsu API datu aprakstu, dod klientiem pilnvaras prasīt tieši to, kas viņiem vajadzīgs, un neko vairāk, atvieglo API attīstību laika gaitā un ļauj izmantot jaudīgus izstrādātāju rīkus. - Lasiet vairāk šeit.

Par Falcor

Falcor ir novatoriska datu platforma, kas nodrošina Netflix saskarnes. Falcor ļauj modelēt visus aizmugures datus kā vienu virtuālo JSON objektu uz jūsu mezgla serveri. Izmantojot klientu, jūs strādājat ar attālo JSON objektu, izmantojot pazīstamas JavaScript darbības, piemēram, get, set and call. Ja jūs zināt savus datus, jūs zināt savu API. - Lasiet vairāk šeit.

Pārsteidzoši REST API iedvesmai

Ja jūs gatavojaties attīstīt Node.js REST API vai izveidot jaunu versiju vecākai, mēs esam apkopojuši četrus reālās dzīves piemērus, kurus ir vērts pārbaudīt:

  • GitHub API
  • Twilio API
  • Stripe API
  • DigitalOcean API

Es ceru, ka tagad jums ir labāka izpratne par to, kā API jāraksta, izmantojot Node.js. Lūdzu, dariet man zināmu komentāros, ja jums kaut kas pietrūkst!

Sākotnēji tas tika publicēts vietnē blog.risingstack.com 2017. gada 21. februārī.