Как да направите своите REST API-та обратно съвместими

Представителният държавен трансфер, известен като REST, е архитектурен стил - набор от ограничения, използвани за внедряване на услуги без гражданство, които се изпълняват на HTTP. RESTful API е този, който отговаря на ограниченията REST. Можете да изградите RESTful API, като използвате много различни езици за програмиране.

Поддържането на обратна съвместимост между различни версии на вашия API е от първостепенно значение за гарантиране, че вашият API ще остане съвместим с всички клиенти, които го консумират. Тази статия представя дискусия за това как можете да поддържате обратна съвместимост във вашите RESTful API.

Пример за съвместимост с API

Да приемем, че имате API в производство, който се консумира от различни клиенти. Сега, ако искате да добавите повече функционалност към API, трябва да се уверите, че клиентите, които използват стария API, ще могат да използват или новия API, или стария. С други думи, трябва да се уверите, че съществуващата функционалност на API ще остане непокътната, докато новата функционалност се добавя.

API е обратно съвместим, ако клиент (програма, написана за консумиране на API), който може да работи с една версия на API, може да работи по същия начин с бъдещите версии на API. С други думи, API е обратно съвместим между изданията, ако клиентите трябва да могат да работят безпроблемно с нова версия на API.

Нека разберем това с пример. Да приемем, че имате API метод с име GetOrders, както е показано в кодовия фрагмент по-долу.

[HttpGet]

[Маршрут („GetOrders“)]

 public IActionResult GetOrders (int customerId, int orderId = 0)

 {

   var резултат = _orderService.GetOrdersForCustomer (

                 customerId, orderId);

   връщане Ok (резултат);

 }

Методът на действие GetOrders приема като параметри идентификатор на клиент и идентификатор на поръчка. Имайте предвид, че вторият параметър, orderID, не е задължителен. Частният метод GetOrdersForCustomer е даден по-долу.

частен списък GetOrdersForCustomer (int customerId, int orderId)

{

   // Напишете код тук, за да върнете един или повече записи за поръчки

}

Методът GetOrdersForCustomer връща всички поръчки на клиент, ако orderId му е предаден като параметър 0. Ако orderId не е нула, той връща една поръчка, отнасяща се до клиента, идентифициран от customerId, предаден като аргумент.

Тъй като вторият параметър на метода за действие GetOrders не е задължителен, можете просто да предадете customerId. Сега, ако промените втория параметър на метода за действие GetOrders, за да го направите задължителен, старите клиенти на API вече няма да могат да използват API.  

[HttpGet]

[Маршрут („GetOrders“)]

 public IActionResult GetOrders (int customerId, int orderId)

 {

   var резултат = _orderService.GetOrdersForCustomer

                 (customerId, orderId);

   връщане Ok (резултат);

 }

И точно по този начин можете да нарушите съвместимостта на вашия API! Разделът, който следва, обсъжда най-добрите практики, които могат да бъдат възприети, за да направят вашия API обратно съвместим.

Съвети за съвместимост с API

След като вече знаем какъв е проблемът, как да проектираме нашите API за препоръчания начин? Как да гарантираме, че нашият RESTful API е обратно съвместим? Този раздел изброява някои от най-добрите практики, които могат да бъдат следвани в това отношение. 

Уверете се, че модулните тестове са преминали

Трябва да имате написани тестове, които ще проверят дали функционалността е непокътната с нова версия на API. Тестовете трябва да бъдат написани по такъв начин, че да се провалят, ако има проблеми със обратната съвместимост. В идеалния случай трябва да имате тестов пакет за тестване на API, който ще се провали и ще предупреди, когато има проблеми със обратната съвместимост на API. Можете също така да имате автоматичен тестов пакет, включен в CI / CD тръбопровода, който проверява за обратна съвместимост и предупреждения, когато има нарушение.

Никога не променяйте поведението на HTTP кодовете за отговор

Никога не трябва да променяте поведението на HTTP кодовете за отговор във вашия API. Ако вашият API връща 500, когато не успее да се свърже с базата данни, не трябва да го променяте на 200. По същия начин, ако връщате HTTP 404, когато възникне изключение и вашите клиенти използват това и обекта за отговор, за да идентифицират какво е отишло грешно, промяната на този метод на API за връщане на HTTP 200 ще наруши съвсем обратната съвместимост.

Никога не променяйте параметрите

Избягвайте да създавате нова версия на API, когато правите само незначителни промени, тъй като това може да е прекалено много. По-добрият подход е да добавите параметри към вашите API методи, за да включите новото поведение. По същия начин не трябва да премахвате параметри от метод на API или да променяте параметър от незадължителен на задължителен (или обратно), тъй като тези промени ще нарушат API и старите клиенти или потребители на API вече няма да могат за работа с API.

Версия на вашия API

Версирането на API е добра практика. Версирането помага да направите вашия API по-гъвкав и адаптивен към промените, като същевременно запазите функционалността непокътната. Също така ви помага да управлявате по-добре промените в кода и по-лесно да се върнете към стария код, ако новият код създава проблеми. Трябва да имате различна версия на вашия RESTful API с всяка основна версия.

Въпреки че REST не предоставя никакви конкретни указания относно версирането на API, можете да версирате своя API по три различни начина: посочване на информацията за версията в URI, съхраняване на информацията за версията в заглавката на персонализираната заявка и добавяне на информация за версиите към HTTP Accept заглавна част. Въпреки че версирането може да ви помогне да поддържате своя API, трябва да избягвате да се опитвате да поддържате много версии на API, за да маркирате чести версии. Това бързо ще стане тромаво и контрапродуктивно. 

Други най-добри практики за API

Никога не трябва да променяте основния URL на API или да променяте съществуващите параметри на низа на заявката. Всяка допълнителна информация трябва да бъде добавена като незадължителен параметър към API метод. Трябва също така да гарантирате, че незадължителните или задължителните елементи, които се предават на API или се връщат от API, никога не се изтриват.

Промените в RESTful API са неизбежни. Ако обаче не се придържате към най-добрите практики и не се уверите, че API е обратно съвместим, промените ви могат да нарушат съвместимостта на API със съществуващите клиенти. API, който е в производство и се консумира от множество клиенти, винаги трябва да бъде обратно съвместим между изданията.