Reprezentacinis valstybės perkėlimas, paprastai žinomas kaip REST, yra architektūros stilius - apribojimų rinkinys, naudojamas įgyvendinant paslaugas be pilietybės, kurios veikia HTTP. RESTful API yra ta, kuri atitinka REST apribojimus. RESTful API galite sukurti naudodami daugybę skirtingų programavimo kalbų.
Palaikyti atgalinį suderinamumą tarp skirtingų jūsų API leidimų yra nepaprastai svarbu užtikrinant, kad jūsų API išliktų suderinama su visais ją vartojančiais klientais. Šiame straipsnyje aptariama, kaip galite išlaikyti atgalinį suderinamumą savo RESTful API.
API suderinamumo pavyzdys
Tarkime, kad turite API gamyboje, kurią naudoja skirtingi klientai. Dabar, jei norite pridėti daugiau funkcijų prie API, turėtumėte užtikrinti, kad klientai, kurie naudoja seną API, galės naudoti naują arba seną. Kitaip tariant, turėtumėte užtikrinti, kad esama API funkcionalumas išliks nepažeistas, kai bus pridėta nauja funkcija.
API yra suderinama atgaline data, jei klientas (programa, parašyta naudoti API), galinti dirbti su viena API versija, gali veikti taip pat ir su būsimomis API versijomis. Kitaip tariant, API yra atgalinė suderinama su leidimais, jei klientai turėtų sugebėti sklandžiai dirbti su nauja API versija.
Supraskime tai su pavyzdžiu. Tarkime, kad turite API metodą pavadinimu „GetOrders“, kaip parodyta žemiau esančiame kodo fragmente.
[HttpGet][Maršrutas („GetOrders“)]
public IActionResult GetOrders (int customerId, int orderId = 0)
{
var rezultatas = _orderService.GetOrdersForCustomer (
customerId, orderId);
grįžti Ok (rezultatas);
}
„GetOrders“ veiksmo metodas priima kliento ID ir užsakymo ID kaip parametrus. Atminkite, kad antrasis parametras „orderID“ yra neprivalomas. „GetOrdersForCustomer“ privatus metodas pateiktas žemiau.
privatus „GetOrdersForCustomer“ sąrašas (int customerId, int orderId){
// Parašykite kodą čia, jei norite grąžinti vieną ar daugiau užsakymo įrašų
}
Metodas „GetOrdersForCustomer“ grąžina visus kliento užsakymus, jei jam perduotas orderId kaip parametras yra 0. Jei orderId nėra nulis, jis grąžina vieną užsakymą, susijusį su klientu, kurį klientas identifikavo kaip argumentą.
Kadangi antrasis veiksmo metodo „GetOrders“ parametras yra neprivalomas, galite tiesiog perduoti „customerId“. Dabar, jei pakeisite antrąjį veiksmo metodo „GetOrders“ parametrą, kad jis būtų privalomas, seni API klientai nebegalės naudoti API.
[HttpGet][Maršrutas („GetOrders“)]
public IActionResult GetOrders (int customerId, int orderId)
{
var rezultatas = _orderService.GetOrdersForCustomer
(kliento ID, užsakymo ID);
grįžti Ok (rezultatas);
}
Ir būtent taip galite sugadinti savo API suderinamumą! Tolesniame skyriuje aptariama geriausia praktika, kurią galima pritaikyti, kad jūsų API būtų suderinama atgaline data.
API suderinamumo patarimai
Dabar, kai žinome, kokia yra problema, kaip mes galime sukurti savo API rekomenduojamą būdą? Kaip užtikrinti, kad mūsų RESTful API būtų suderinama atgaline data? Šiame skyriuje pateikiama keletas geriausių praktikų, kurių galima laikytis šiuo klausimu.
Įsitikinkite, kad įrenginio bandymai yra sėkmingi
Turėtumėte parašyti testus, kurie patikrins, ar funkcija nepažeista naudojant naują API leidimą. Testai turėtų būti parašyti taip, kad jie turėtų nepavykti, jei yra kokių nors atgalinio suderinamumo problemų. Idealiu atveju turėtumėte turėti API testavimo rinkinį, kuris nepavyks ir perspės, kai kyla problemų dėl atgalinio API suderinamumo. Taip pat galite turėti automatinį bandymų rinkinį, prijungtą prie CI / CD vamzdyno, kuris tikrina atgalinį suderinamumą ir įspėja, kai yra pažeidimas.
Niekada nekeiskite HTTP atsako kodų elgsenos
Niekada neturėtumėte keisti HTTP atsakymo kodų elgsenos savo API. Jei jūsų API grąžina 500, kai nepavyksta prisijungti prie duomenų bazės, neturėtumėte jos pakeisti į 200. Panašiai, jei grąžinate HTTP 404, kai įvyksta išimtis, o jūsų klientai naudoja šį ir atsakymo objektą, kad nustatytų, kas vyko neteisinga, pakeitus šį API metodą, kad būtų grąžinta HTTP 200, bus visiškai sugadintas atgalinis suderinamumas.
Niekada nekeiskite parametrų
Venkite kurti naują API versiją, kai atliekate tik nedidelius pakeitimus, nes tai gali būti per daug. Geresnis būdas yra pridėti parametrus prie API metodų, kad būtų įtrauktas naujas elgesys. Tuo pačiu principu neturėtumėte pašalinti parametrų iš API metodo arba pakeisti parametrą iš neprivalomo į privalomą (arba atvirkščiai), nes šie pakeitimai sulaužys API ir seni klientai ar API vartotojai nebegalės dirbti su API.
Versijos API
API versijos yra gera praktika. Versijų kūrimas padeda padaryti jūsų API lankstesnę ir pritaikomą pokyčiams, išlaikant nepakitusią funkciją. Tai taip pat padeda geriau valdyti kodo pakeitimus ir lengviau grįžti prie senojo kodo, jei dėl naujo kodo kyla problemų. Kiekviename pagrindiniame leidime turėtumėte turėti skirtingą „RESTful“ API versiją.
Nors REST nepateikia jokių konkrečių API versijų gairių, galite ją versijinti trimis skirtingais būdais: nurodydami informacijos apie versiją versiją URI, informacijos apie versiją įrašymą pasirinktinės užklausos antraštėje ir versijų informacijos pridėjimą prie „HTTP Accept“ antraštė. Nors versijų kūrimas gali padėti išlaikyti jūsų API, turėtumėte vengti bandyti išlaikyti daugybę API versijų, kad pažymėtumėte dažnus leidimus. Tai greitai taps sudėtinga ir neproduktyvu.
Kita geriausia API praktika
Niekada neturėtumėte keisti API šakninio URL ar modifikuoti esamų užklausos eilutės parametrų. Bet kokia papildoma informacija turėtų būti pridėta kaip neprivalomas parametras prie API metodo. Taip pat turėtumėte užtikrinti, kad neprivalomi arba privalomi elementai, kurie perduodami API arba yra grąžinti iš API, niekada nebus ištrinti.
RESTful API pakeitimai yra neišvengiami. Tačiau, jei nesilaikysite geriausios praktikos ir užtikrinsite, kad API būtų suderinama atgal, jūsų pakeitimai gali sugadinti API suderinamumą su esamais klientais. API, kuri yra gaminama ir kurią naudoja keli klientai, visada turėtų būti suderinama su leidimais atgaline data.
