Representational State Transfer, almindeligvis kendt som REST, er en arkitektonisk stil - et sæt begrænsninger, der bruges til at implementere statsløse tjenester, der kører på HTTP. En RESTful API er en, der overholder REST-begrænsningerne. Du kan oprette RESTful API'er ved hjælp af mange forskellige programmeringssprog.
Det er meget vigtigt at opretholde bagudkompatibilitet mellem forskellige udgivelser af din API for at sikre, at din API forbliver kompatibel med alle de klienter, der bruger det. Denne artikel præsenterer en diskussion om, hvordan du kan opretholde bagudkompatibilitet i dine RESTful API'er.
Eksempel på API-kompatibilitet
Antag at du har en API i produktion, der forbruges af forskellige klienter. Hvis du nu vil tilføje mere funktionalitet til API'en, skal du sikre dig, at de klienter, der bruger den gamle API, kan bruge enten den nye API eller den gamle. Med andre ord skal du sikre dig, at API'ens eksisterende funktionalitet forbliver intakt, mens den nye funktionalitet tilføjes.
En API er bagudkompatibel, hvis en klient (et program skrevet til at forbruge API'en), der kan arbejde med en version af API'en, kan arbejde på samme måde med fremtidige versioner af API'en. Med andre ord er en API bagudkompatibel mellem udgivelser, hvis klienterne er i stand til at arbejde med en ny version af API'en problemfrit.
Lad os forstå dette med et eksempel. Antag at du har en API-metode ved navn GetOrders som vist i kodestykket nedenfor.
[HttpGet][Rute ("GetOrders")]
offentlige IActionResult GetOrders (int customerId, int orderId = 0)
{
var result = _orderService.GetOrdersForCustomer (
customerId, orderId);
returner Ok (resultat);
}
Handlingsmetoden GetOrders accepterer et kunde-id og et ordre-id som parametre. Bemærk, at den anden parameter, orderID, er valgfri. Den private metode GetOrdersForCustomer er angivet nedenfor.
privat liste GetOrdersForCustomer (int customerId, int orderId){
// Skriv kode her for at returnere en eller flere ordreoptegnelser
}
GetOrdersForCustomer-metoden returnerer alle ordrer fra en kunde, hvis orderId sendt til den som en parameter er 0. Hvis orderId ikke er nul, returnerer den en ordre, der vedrører den kunde, der er identificeret af customerId, der er sendt som et argument.
Da den anden parameter i GetOrders-handlingsmetoden er valgfri, kan du bare videregive customerId. Hvis du nu ændrer den anden parameter i handlingsmetoden GetOrders for at gøre det obligatorisk, kan de gamle klienter i API'en ikke længere bruge API'en.
[HttpGet][Rute ("GetOrders")]
offentlige IActionResult GetOrders (int customerId, int orderId)
{
var result = _orderService.GetOrdersForCustomer
(kunde-id, ordre-id);
returner Ok (resultat);
}
Og det er nøjagtigt, hvordan du kan bryde kompatibiliteten af din API! Det følgende afsnit diskuterer de bedste fremgangsmåder, der kan anvendes til at gøre din API bagudkompatibel.
API-kompatibilitetstip
Nu hvor vi ved, hvad problemet handler om, hvordan designer vi vores API'er på den anbefalede måde? Hvordan sikrer vi, at vores RESTful API er bagudkompatibel? Dette afsnit viser nogle af de bedste fremgangsmåder, der kan følges i denne henseende.
Sørg for, at enhedstestene består
Du bør have test skrevet, der vil kontrollere, om funktionaliteten er intakt med en ny udgivelse af API'en. Testene skal skrives på en sådan måde, at de skulle mislykkes, hvis der er problemer med bagudkompatibilitet. Ideelt set skal du have en testpakke til API-test, der mislykkes og advarer, når der er problemer med bagudkompatibilitet af API. Du kan også få en automatisk testpakke tilsluttet CI / CD-pipelinen, der kontrollerer for bagudkompatibilitet og advarsler, når der er en overtrædelse.
Ændr aldrig adfærd for HTTP-responskoder
Du bør aldrig ændre adfærd for HTTP-svarkoder i din API. Hvis din API returnerer 500, når den ikke opretter forbindelse til databasen, skal du ikke ændre den til 200. På samme måde, hvis du returnerer HTTP 404, når en undtagelse opstår, og dine klienter bruger dette og svarobjektet til at identificere, hvad der gik forkert, hvis denne API-metode ændres for at returnere HTTP 200, brydes den bagudkompatibilitet helt.
Skift aldrig parametre
Undgå at oprette en ny version af API'et, når du kun foretager mindre ændringer, da det kan være for stort. En bedre tilgang er at tilføje parametre til dine API-metoder for at indarbejde den nye adfærd. På samme måde bør du ikke fjerne parametre fra en API-metode eller ændre en parameter fra valgfri til obligatorisk (eller omvendt), da disse ændringer vil bryde API'en, og gamle klienter eller forbrugere af API'en ikke længere er i stand at arbejde med API'en.
Version din API
Versioning af API'er er en god praksis. Versioning hjælper med at gøre din API mere fleksibel og tilpasse sig ændringer, mens den holder funktionaliteten intakt. Det hjælper dig også med at administrere ændringer til koden bedre og lettere vende tilbage til gammel kode, hvis den nye kode forårsager problemer. Du skal have en anden version af din RESTful API med hver større udgivelse.
Selvom REST ikke giver nogen specifik vejledning om API-versionering, kan du versionere din API på tre forskellige måder: Angivelse af versionoplysningerne i URI, lagring af versionoplysningerne i den tilpassede anmodningsoverskrift og tilføjelse af versionsoplysninger til HTTP Accept header. Selvom versionering kan hjælpe dig med at vedligeholde din API, bør du undgå at prøve at vedligeholde mange versioner af API'en for at markere hyppige udgivelser. Dette bliver hurtigt besværligt og kontraproduktivt.
Andre bedste praksis for API
Du bør aldrig ændre rod-URL'en til en API eller ændre de eksisterende forespørgselsstrengparametre. Eventuelle yderligere oplysninger skal føjes som en valgfri parameter til en API-metode. Du skal også sikre, at valgfrie eller obligatoriske elementer, der sendes til en API eller returneres fra en API, aldrig slettes.
Ændringer i en RESTful API er uundgåelige. Men medmindre du overholder de bedste fremgangsmåder og sikrer, at API'en er bagudkompatibel, kan dine ændringer bryde API's kompatibilitet med eksisterende klienter. En API, der er i produktion og forbruges af flere klienter, skal altid være bagudkompatibel mellem udgivelser.
