Hoe u uw REST API's achterwaarts compatibel maakt

Representational State Transfer, algemeen bekend als REST, is een architecturale stijl: een reeks beperkingen die worden gebruikt om stateless services te implementeren die op HTTP draaien. Een RESTful API is er een die voldoet aan de REST-beperkingen. U kunt RESTful API's bouwen met veel verschillende programmeertalen.

Het behouden van achterwaartse compatibiliteit tussen verschillende releases van uw API is van het grootste belang om ervoor te zorgen dat uw API compatibel blijft met alle clients die deze gebruiken. In dit artikel wordt besproken hoe u achterwaartse compatibiliteit in uw RESTful API's kunt behouden.

API-compatibiliteitsvoorbeeld

Stel dat u een API in productie heeft die door verschillende klanten wordt gebruikt. Als u nu meer functionaliteit aan de API wilt toevoegen, moet u ervoor zorgen dat de clients die de oude API gebruiken, de nieuwe API of de oude kunnen gebruiken. Met andere woorden, u moet ervoor zorgen dat de bestaande functionaliteit van de API intact blijft terwijl de nieuwe functionaliteit wordt toegevoegd.

Een API is achterwaarts compatibel als een client (een programma dat is geschreven om de API te gebruiken) die met één versie van de API kan werken, op dezelfde manier kan werken met toekomstige versies van de API. Met andere woorden, een API is achterwaarts compatibel tussen releases als de clients naadloos zouden moeten kunnen werken met een nieuwe versie van de API.

Laten we dit begrijpen met een voorbeeld. Stel dat u een API-methode heeft met de naam GetOrders, zoals weergegeven in het onderstaande codefragment.

[HttpGet]

[Route ("GetOrders")]

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

 {

   var resultaat = _orderService.GetOrdersForCustomer (

                 klant-id, order-id);

   retourneer Ok (resultaat);

 }

De actiemethode GetOrders accepteert een klant-ID en een bestel-ID als parameters. Merk op dat de tweede parameter, orderID, optioneel is. De privémethode GetOrdersForCustomer wordt hieronder gegeven.

privélijst GetOrdersForCustomer (int customerId, int orderId)

{

   // Schrijf hier code om een ​​of meer orderrecords te retourneren

}

De methode GetOrdersForCustomer retourneert alle orders van een klant als de orderId die eraan is doorgegeven als parameter 0 is. Als de orderId niet-nul is, retourneert het één order die betrekking heeft op de klant die is geïdentificeerd door de customerId die is doorgegeven als een argument.

Aangezien de tweede parameter van de GetOrders-actiemethode optioneel is, kunt u de customerId gewoon doorgeven. Als u nu de tweede parameter van de actiemethode GetOrders wijzigt om deze verplicht te maken, kunnen de oude clients van de API de API niet meer gebruiken.  

[HttpGet]

[Route ("GetOrders")]

 openbare IActionResult GetOrders (int customerId, int orderId)

 {

   var resultaat = _orderService.GetOrdersForCustomer

                 (klant-id, order-id);

   retourneer Ok (resultaat);

 }

En dat is precies hoe u de compatibiliteit van uw API kunt doorbreken! In het volgende gedeelte worden de best practices besproken die kunnen worden toegepast om uw API achterwaarts compatibel te maken.

API-compatibiliteitstips

Nu we weten waar het probleem over gaat, hoe ontwerpen we onze API's dan op de aanbevolen manier? Hoe zorgen we ervoor dat onze RESTful API achterwaarts compatibel is? Dit gedeelte bevat enkele van de beste praktijken die in dit verband kunnen worden gevolgd. 

Zorg ervoor dat de unit-tests slagen

U moet tests hebben geschreven die zullen verifiëren of de functionaliteit intact is met een nieuwe release van de API. De tests moeten zo worden geschreven dat ze niet slagen als er achterwaartse compatibiliteitsproblemen zijn. Idealiter zou u een testsuite moeten hebben voor API-testen die mislukt en waarschuwt wanneer er problemen zijn met achterwaartse compatibiliteit van de API. U kunt ook een geautomatiseerde testsuite laten aansluiten op de CI / CD-pijplijn die controleert op achterwaartse compatibiliteit en waarschuwt wanneer er een overtreding is.

Verander nooit het gedrag van HTTP-antwoordcodes

U mag nooit het gedrag van HTTP-antwoordcodes in uw API wijzigen. Als uw API 500 retourneert wanneer het geen verbinding kan maken met de database, moet u dit niet wijzigen in 200. Evenzo, als u HTTP 404 retourneert wanneer er een uitzondering optreedt, en uw klanten dit en het responsobject gebruiken om te identificeren wat er is gebeurd onjuist is, zal het wijzigen van deze API-methode om HTTP 200 te retourneren de achterwaartse compatibiliteit helemaal verbreken.

Verander nooit parameters

Vermijd het maken van een nieuwe versie van de API wanneer u slechts kleine wijzigingen aanbrengt, omdat dit misschien overdreven is. Een betere benadering is om parameters toe te voegen aan uw API-methoden om het nieuwe gedrag op te nemen. Op dezelfde manier mag u geen parameters van een API-methode verwijderen of een parameter wijzigen van optioneel in verplicht (of vice versa), aangezien deze wijzigingen de API zullen verbreken en oude clients of gebruikers van de API niet langer in staat zullen zijn om met de API te werken.

Version uw API

Versiebeheer van API's is een goede gewoonte. Versiebeheer helpt uw ​​API flexibeler te maken en aan te passen aan wijzigingen, terwijl de functionaliteit intact blijft. Het helpt je ook om wijzigingen in de code beter te beheren en gemakkelijker terug te keren naar oude code als de nieuwe code problemen veroorzaakt. U zou bij elke belangrijke release een andere versie van uw RESTful API moeten hebben.

Hoewel REST geen specifieke richtlijnen biedt voor API-versiebeheer, kunt u uw API op drie verschillende manieren versieren: specificeer de versie-informatie in de URI, sla de versiegegevens op in de aangepaste aanvraagheader en voeg de versie-informatie toe aan de HTTP Accept. koptekst. Hoewel versiebeheer u kan helpen uw API te onderhouden, moet u voorkomen dat u probeert veel versies van de API te onderhouden om frequente releases te markeren. Dit wordt snel omslachtig en contraproductief. 

Andere praktische tips voor API

U mag de root-URL van een API nooit wijzigen of de bestaande parameters van de querytekenreeks wijzigen. Eventuele aanvullende informatie moet als een optionele parameter aan een API-methode worden toegevoegd. U moet er ook voor zorgen dat optionele of verplichte elementen die worden doorgegeven aan een API of worden geretourneerd door een API, nooit worden verwijderd.

Veranderingen aan een RESTful API zijn onvermijdelijk. Tenzij u zich echter aan de best practices houdt en ervoor zorgt dat de API achterwaarts compatibel is, kunnen uw wijzigingen de compatibiliteit van de API met bestaande clients verbreken. Een API die in productie is en wordt gebruikt door meerdere klanten, moet altijd achterwaarts compatibel zijn tussen releases.