Reprezentačný prenos štátu, všeobecne známy ako REST, je architektonický štýl - sada obmedzení používaných na implementáciu služieb bez štátnej príslušnosti, ktoré bežia na protokole HTTP. RESTful API je také, ktoré vyhovuje obmedzeniam REST. Rozhrania RESTful API môžete vytvoriť pomocou mnohých rôznych programovacích jazykov.
Udržiavanie spätnej kompatibility medzi rôznymi vydaniami vášho API je nanajvýš dôležité pre zabezpečenie toho, aby vaše API zostalo kompatibilné so všetkými klientmi, ktorí ho konzumujú. Tento článok predstavuje diskusiu o tom, ako môžete zachovať spätnú kompatibilitu svojich rozhraní RESTful API.
Príklad kompatibility API
Predpokladajme, že máte vo výrobe API, ktoré spotrebúvajú rôzni klienti. Ak teraz chcete do rozhrania API pridať ďalšie funkcie, mali by ste sa uistiť, že klienti, ktorí používajú staré rozhranie API, budú môcť používať buď nové, alebo staré rozhranie API. Inými slovami, mali by ste zabezpečiť, aby existujúca funkčnosť API zostala nedotknutá, kým bude pridaná nová funkčnosť.
API je spätne kompatibilné, ak klient (program napísaný na konzumáciu API), ktorý dokáže pracovať s jednou verziou API, môže pracovať rovnakým spôsobom s budúcimi verziami API. Inými slovami, API je spätne kompatibilné medzi vydaniami, ak by klienti mali byť schopní bezproblémovo pracovať s novou verziou API.
Poďme to pochopiť na príklade. Predpokladajme, že máte metódu API s názvom GetOrders, ako je uvedené v útržku kódu nižšie.
[HttpGet][Route („GetOrders“)]
public IActionResult GetOrders (int customerId, int orderId = 0)
{
var result = _orderService.GetOrdersForCustomer (
customerId, orderId);
návrat Ok (výsledok);
}
Metóda akcie GetOrders prijíma ako parametre ID zákazníka a ID objednávky. Pamätajte, že druhý parameter, orderID, je voliteľný. Ďalej je uvedená súkromná metóda GetOrdersForCustomer.
súkromný zoznam GetOrdersForCustomer (int customerId, int orderId){
// Sem napíšete kód, aby ste vrátili jeden alebo viac záznamov objednávky
}
Metóda GetOrdersForCustomer vráti všetky objednávky zákazníka, ak je hodnota parametra orderId odovzdaná ako parameter 0. Ak je hodnota parametra orderId nenulová, vráti jednu objednávku zodpovedajúcu zákazníkovi identifikovanému parametrom customerId, ktorý bol odovzdaný ako argument.
Pretože druhý parameter metódy akcie GetOrders je voliteľný, stačí zadať customerId. Ak teraz zmeníte druhý parameter akčnej metódy GetOrders tak, aby bol povinný, starí klienti API už nebudú môcť API používať.
[HttpGet][Route („GetOrders“)]
public IActionResult GetOrders (int customerId, int orderId)
{
var result = _orderService.GetOrdersForCustomer
(customerId, orderId);
návrat Ok (výsledok);
}
A presne takto môžete narušiť kompatibilitu vášho API! Nasledujúca časť pojednáva o osvedčených postupoch, ktoré je možné prijať, aby bola vaša API spätne kompatibilná.
Tipy na kompatibilitu s API
Teraz, keď vieme, o čom je problém, ako navrhneme naše API odporúčaným spôsobom? Ako zabezpečíme, aby bolo naše RESTful API spätne kompatibilné? V tejto časti sú uvedené niektoré z najlepších postupov, ktoré je možné v tejto súvislosti dodržiavať.
Uistite sa, že testy jednotky prešli
Mali by ste mať pripravené testy, ktoré overia, či je funkčnosť neporušená s novým vydaním API. Testy by mali byť napísané tak, aby zlyhali, ak sa vyskytnú problémy so spätnou kompatibilitou. V ideálnom prípade by ste mali mať testovaciu sadu na testovanie API, ktorá zlyhá a upozorní vás, keď sa vyskytnú problémy so spätnou kompatibilitou API. Do potrubia CI / CD môžete tiež zapojiť automatizovanú testovaciu sadu, ktorá kontroluje spätnú kompatibilitu a upozorňuje na porušenie.
Nikdy nemeňte správanie kódov odpovedí HTTP
Správanie kódov odpovedí HTTP by ste nikdy nemali meniť vo svojom rozhraní API. Ak vaše API vráti 500, keď sa nedokáže pripojiť k databáze, nemali by ste to zmeniť na 200. Podobne, ak vraciate HTTP 404, keď dôjde k výnimke, a vaši klienti používajú tento objekt a objekt odpovede na identifikáciu toho, čo prešlo nesprávne, zmena tejto metódy API na návrat HTTP 200 úplne spôsobí spätnú kompatibilitu.
Nikdy nemeňte parametre
Ak robíte iba malé zmeny, nevytvárajte novú verziu API, pretože by to mohlo byť prehnané. Lepším prístupom je pridanie parametrov k vašim metódam API na začlenenie nového správania. Z rovnakého dôvodu by ste nemali odstraňovať parametre z metódy API alebo meniť parameter z voliteľného na povinný (alebo naopak), pretože tieto zmeny rozbijú API a starí klienti alebo spotrebitelia API už nebudú môcť pracovať s API.
Verzia vášho API
Verzia API je osvedčeným postupom. Správa verzií umožňuje, aby bolo vaše rozhranie API flexibilnejšie a prispôsobiteľnejšie zmenám, pričom funkčnosť zostane nedotknutá. Pomáha vám tiež lepšie spravovať zmeny v kóde a ľahšie sa vrátiť k starému kódu, ak nový kód spôsobuje problémy. S každým hlavným vydaním by ste mali mať inú verziu svojho rozhrania RESTful API.
Aj keď REST neposkytuje žiadne konkrétne pokyny týkajúce sa spravovania verzií API, môžete svoje API vytvoriť verziou tromi rôznymi spôsobmi: zadaním informácií o verzii v identifikátore URI, uložením informácií o verzii do hlavičky vlastnej požiadavky a pridaním informácií o verzii do protokolu HTTP Accept. hlavička. Aj keď riadenie verzií vám môže pomôcť pri údržbe vášho API, mali by ste sa vyhnúť pokusom o údržbu mnohých verzií API na označenie častých vydaní. To sa rýchlo stane ťažkopádnym a kontraproduktívnym.
Ďalšie osvedčené postupy týkajúce sa rozhrania API
Nikdy by ste nemali meniť koreňovú adresu URL API alebo upravovať existujúce parametre reťazca dotazu. Akékoľvek ďalšie informácie by sa mali pridať ako voliteľný parameter k metóde API. Mali by ste sa tiež ubezpečiť, že voliteľné alebo povinné prvky, ktoré sa odovzdajú API alebo sa vrátia z API, sa nikdy neodstránia.
Zmeny v rozhraní RESTful API sú nevyhnutné. Pokiaľ však nedodržíte osvedčené postupy a nezabezpečíte spätnú kompatibilitu rozhrania API, vaše zmeny môžu narušiť kompatibilitu rozhrania API s existujúcimi klientmi. Rozhranie API, ktoré je v produkcii a je spotrebované viacerými klientmi, by malo byť vždy spätne kompatibilné medzi vydaniami.
