Reprezentativni državni prenos, splošno znan kot REST, je arhitekturni slog - niz omejitev, ki se uporabljajo za izvajanje storitev brez državljanstva, ki se izvajajo na HTTP. API RESTful je tisti, ki ustreza omejitvam REST. API-je RESTful lahko sestavite z uporabo številnih različnih programskih jezikov.
Ohranjanje združljivosti za nazaj med različnimi izdajami vašega API-ja je izjemnega pomena za zagotovitev, da bo vaš API ostal združljiv z vsemi odjemalci, ki ga uporabljajo. Ta članek predstavlja razpravo o tem, kako lahko v svojih API-jih RESTful ohranite združljivost za nazaj.
Primer združljivosti API
Predpostavimo, da imate API v proizvodnji, ki ga uporabljajo različne stranke. Če želite API-ju dodati več funkcij, zagotovite, da bodo odjemalci, ki uporabljajo stari API, lahko uporabljali novi ali stari API. Z drugimi besedami, poskrbite, da bo ob dodajanju nove funkcionalnosti obstoječa funkcionalnost API-ja ostala nedotaknjena.
API je združljiv z nazaj, če lahko odjemalec (program, napisan za uporabo API-ja), ki lahko deluje z eno različico API-ja, deluje enako kot s prihodnjimi različicami API-ja. Z drugimi besedami, API je združljiv med izdajami, če bi stranke lahko brez težav delovale z novo različico API-ja.
Razumimo to na primeru. Predpostavimo, da imate metodo API z imenom GetOrders, kot je prikazano v spodnjem delčku kode.
[HttpGet][Pot ("GetOrders")]
javni IActionResult GetOrders (int customerId, int orderId = 0)
{
var rezultat = _orderService.GetOrdersForCustomer (
customerId, orderId);
vrni Ok (rezultat);
}
Metoda dejanja GetOrders kot parametra sprejema ID stranke in ID naročila. Drugi parameter, orderID, ni obvezen. Zasebna metoda GetOrdersForCustomer je podana spodaj.
zasebni seznam GetOrdersForCustomer (int customerId, int orderId){
// Tukaj napišite kodo, da vrnete enega ali več zapisov o naročilu
}
Metoda GetOrdersForCustomer vrne vsa naročila stranke, če ji je orderId posredovana kot parameter 0. Če orderId ni nič, vrne eno naročilo, ki se nanaša na kupca, ki ga je strankaId posredovala kot argument.
Ker drugi parameter metode dejanja GetOrders ni obvezen, lahko preprosto posredujete customerId. Če zdaj spremenite drugi parameter akcijske metode GetOrders, da bo obvezen, stari odjemalci API-ja API-ja ne bodo mogli več uporabljati.
[HttpGet][Pot ("GetOrders")]
javni IActionResult GetOrders (int customerId, int orderId)
{
var rezultat = _orderService.GetOrdersForCustomer
(customerId, orderId);
vrni Ok (rezultat);
}
In točno tako lahko prekinete združljivost svojega API-ja! V naslednjem razdelku so opisane najboljše prakse, ki jih je mogoče sprejeti, da bo vaš API združljiv z nazaj.
Nasveti za združljivost API-jev
Zdaj, ko vemo, v čem je težava, kako oblikujemo naše API-je na priporočen način? Kako naj zagotovimo, da je naš API RESTful združljiv z nazaj? V tem razdelku je navedenih nekaj najboljših praks, ki jih je v zvezi s tem mogoče upoštevati.
Prepričajte se, da so preskusi enote uspešno opravljeni
Morali bi imeti napisane teste, ki bodo z novo izdajo API-ja preverili, ali je funkcionalnost nedotaknjena. Preskusi naj bodo napisani tako, da ne bodo uspeli, če pride do težav z združljivostjo nazaj. V idealnem primeru bi morali imeti testni paket za testiranje API-ja, ki ne bo uspel in vas opozoril, če obstajajo težave s povratno združljivostjo API-ja. Lahko imate tudi avtomatiziran testni paket, priključen na cevovod CI / CD, ki preverja združljivost in opozorila v primeru kršitve.
Nikoli ne spreminjajte vedenja odzivnih kod HTTP
Nikoli ne smete spremeniti vedenja odzivnih kod HTTP v vašem API-ju. Če vaš API vrne 500, ko se ne uspe povezati z bazo podatkov, ga ne bi smeli spremeniti na 200. Podobno, če vračate HTTP 404, ko pride do izjeme in vaše stranke uporabljajo to in objekt odziva, da prepoznajo, kaj je narobe, če spremenite to metodo API za vrnitev HTTP 200, bo v celoti prekinjena združljivost za nazaj.
Nikoli ne spreminjajte parametrov
Izogibajte se ustvarjanju nove različice API-ja, če vnesete le manjše spremembe, saj je morda preveč. Boljši pristop je, da v metode API dodate parametre, da vključite novo vedenje. Iz istega razloga ne bi smeli odstranjevati parametrov iz metode API ali spreminjati parametra iz neobveznega v obveznega (ali obratno), saj bodo te spremembe prekinile API in stari odjemalci ali potrošniki API-ja ne bodo mogli več za delo z API-jem.
Različite svoj API
Različenje API-jev je dobra praksa. Različice vam pomagajo, da je vaš API bolj prilagodljiv in prilagodljiv spremembam, hkrati pa ohranja funkcionalnost nedotaknjeno. Pomaga tudi pri boljšem upravljanju sprememb kode in lažji vrnitvi nazaj na staro kodo, če nova koda povzroča težave. Pri vsaki večji izdaji bi morali imeti različico različice API-ja RESTful.
Čeprav REST ne vsebuje nobenih posebnih navodil o različicah API-jev, lahko API-je različic spremenite na tri različne načine: določanje informacij o različici v URI-ju, shranjevanje informacij o različici v glavo zahteve po meri in dodajanje informacij o različicah v HTTP Accept glava. Čeprav vam lahko različice pomagajo vzdrževati vaš API, se izogibajte poskusom vzdrževanja številnih različic API-ja, da označite pogoste izdaje. To bo hitro postalo okorno in kontraproduktivno.
Druge najboljše prakse API
Nikoli ne smete spreminjati korenskega URL-ja API-ja ali spreminjati obstoječih parametrov niza poizvedbe. Vse dodatne informacije je treba metodi API dodati kot neobvezen parameter. Zagotoviti morate tudi, da se izbirni ali obvezni elementi, ki se posredujejo API-ju ali se vrnejo iz API-ja, nikoli ne izbrišejo.
Spremembe API-ja RESTful so neizogibne. Če pa ne upoštevate najboljših praks in zagotovite, da je API združljiv z nazaj, lahko vaše spremembe prekinejo združljivost API-ja z obstoječimi odjemalci. API, ki je v izdelavi in ga uporablja več odjemalcev, mora biti vedno združljiv med izdajami.
