Reprezentativní přenos státu, běžně známý jako REST, je architektonický styl - sada omezení používaných k implementaci bezstavových služeb, které běží na HTTP. Rozhraní RESTful API je takové, které odpovídá omezením REST. Rozhraní RESTful API můžete vytvářet pomocí mnoha různých programovacích jazyků.
Udržování zpětné kompatibility mezi různými verzemi vašeho API je nanejvýš důležité pro zajištění toho, aby vaše API zůstalo kompatibilní se všemi klienty, kteří jej konzumují. Tento článek představuje diskusi o tom, jak můžete udržovat zpětnou kompatibilitu ve svých RESTful API.
Příklad kompatibility API
Předpokládejme, že máte ve výrobě API, které spotřebovávají různí klienti. Nyní, pokud chcete do rozhraní API přidat další funkce, měli byste zajistit, aby klienti, kteří používají staré rozhraní API, mohli používat buď nové rozhraní API, nebo staré rozhraní. Jinými slovy byste měli zajistit, že stávající funkce rozhraní API zůstanou nedotčeny, dokud bude přidána nová funkce.
API je zpětně kompatibilní, pokud klient (program napsaný tak, aby spotřebovával API), který může pracovat s jednou verzí API, může fungovat stejným způsobem s budoucími verzemi API. Jinými slovy, API je zpětně kompatibilní mezi verzemi, pokud by klienti měli být schopni bezproblémově pracovat s novou verzí API.
Pochopme to na příkladu. Předpokládejme, že máte metodu API s názvem GetOrders, jak je znázorněno v úryvku kódu níže.
[HttpGet][Route („GetOrders“)]
public IActionResult GetOrders (int customerId, int orderId = 0)
{
var result = _orderService.GetOrdersForCustomer (
customerId, orderId);
návrat Ok (výsledek);
}
Metoda akce GetOrders přijímá jako parametry ID zákazníka a ID objednávky. Všimněte si, že druhý parametr, orderID, je volitelný. Soukromá metoda GetOrdersForCustomer je uvedena níže.
soukromý seznam GetOrdersForCustomer (int customerId, int orderId){
// Sem napište kód pro vrácení jednoho nebo více záznamů objednávky
}
Metoda GetOrdersForCustomer vrací všechny objednávky zákazníka, pokud je parametr orderId předán jako parametr 0. Pokud je hodnota orderId nenulová, vrátí jednu objednávku týkající se zákazníka identifikovaného zákazníkem předaného jako argument.
Vzhledem k tomu, že druhý parametr metody akce GetOrders je volitelný, stačí předat customerId. Pokud nyní změníte druhý parametr akční metody GetOrders tak, aby byl povinný, starí klienti API již nebudou moci API používat.
[HttpGet][Route („GetOrders“)]
public IActionResult GetOrders (int customerId, int orderId)
{
var result = _orderService.GetOrdersForCustomer
(customerId, orderId);
návrat Ok (výsledek);
}
A přesně tak můžete narušit kompatibilitu svého API! V následující části jsou popsány osvědčené postupy, které lze přijmout, aby vaše rozhraní API bylo zpětně kompatibilní.
Tipy pro kompatibilitu s API
Nyní, když víme, o co jde, jak navrhujeme naše API doporučeným způsobem? Jak zajistíme, aby naše RESTful API bylo zpětně kompatibilní? V této části jsou uvedeny některé z osvědčených postupů, které lze v tomto ohledu dodržovat.
Ujistěte se, že testy jednotky proběhly úspěšně
Měli byste mít napsané testy, které ověří, zda je funkce neporušená s novým vydáním API. Testy by měly být psány takovým způsobem, že by měly selhat, pokud se vyskytnou problémy se zpětnou kompatibilitou. V ideálním případě byste měli mít testovací sadu pro testování API, která selže a upozorní vás, když dojde k problémům se zpětnou kompatibilitou API. Do kanálu CI / CD můžete také zapojit automatickou testovací sadu, která kontroluje zpětnou kompatibilitu a upozorní na případné narušení.
Nikdy neměňte chování kódů odpovědi HTTP
Nikdy byste neměli měnit chování kódů odpovědí HTTP ve vašem API. Pokud vaše API vrátí 500, když se nepodaří připojit k databázi, neměli byste to změnit na 200. Podobně, pokud vracíte HTTP 404, když dojde k výjimce, a vaši klienti používají tento a objekt odpovědi k identifikaci toho, co šlo špatně, změna této metody API na návrat HTTP 200 způsobí úplné porušení zpětné kompatibility.
Nikdy neměňte parametry
Vyvarujte se vytváření nové verze API, když provádíte jen drobné změny, protože by to mohlo být přehnané. Lepším přístupem je přidání parametrů do vašich metod API k začlenění nového chování. Ze stejného tokenu byste neměli odebírat parametry z metody API ani měnit parametr z volitelného na povinný (nebo naopak), protože tyto změny rozbijí API a starí klienti nebo spotřebitelé API již nebudou moci pracovat s API.
Verze vašeho API
Správa verzí API je dobrým postupem. Správa verzí pomáhá učinit vaše rozhraní API flexibilnějším a přizpůsobivějším změnám při zachování nedotčené funkčnosti. Pomůže vám také lépe spravovat změny kódu a snadněji se vrátit zpět ke starému kódu, pokud nový kód způsobí problémy. S každou hlavní verzí byste měli mít jinou verzi svého RESTful API.
Ačkoli REST neposkytuje žádné konkrétní pokyny k verzování API, můžete své API verzovat třemi různými způsoby: zadáním informací o verzi v URI, uložením informací o verzi do záhlaví vlastního požadavku a přidáním informací o verzích do HTTP Accept záhlaví. Ačkoli správa verzí vám může pomoci udržovat vaše API, měli byste se vyhnout pokusu udržovat mnoho verzí API k označení častých vydání. To se rychle stane těžkopádným a kontraproduktivním.
Další osvědčené postupy API
Nikdy byste neměli měnit kořenovou adresu URL API ani upravovat stávající parametry řetězce dotazu. Jakékoli další informace by měly být přidány jako volitelný parametr k metodě API. Měli byste také zajistit, aby nikdy nebyly odstraněny volitelné nebo povinné prvky, které jsou předány API nebo jsou vráceny z API.
Změny rozhraní RESTful API jsou nevyhnutelné. Pokud však nedodržíte osvědčené postupy a nezajistíte zpětnou kompatibilitu rozhraní API, mohou vaše změny narušit kompatibilitu rozhraní API se stávajícími klienty. Rozhraní API, které je ve výrobě a je spotřebováváno více klienty, by mělo být vždy zpětně kompatibilní mezi verzemi.
