Programmering

Hvordan lage REST API-ene bakoverkompatible

Representational State Transfer, ofte kjent som REST, er en arkitektonisk stil - et sett med begrensninger som brukes til å implementere statsløse tjenester som kjører på HTTP. En RESTful API er en som er i samsvar med REST-begrensningene. Du kan bygge RESTful APIer ved hjelp av mange forskjellige programmeringsspråk.

Å opprettholde bakoverkompatibilitet mellom forskjellige utgivelser av API-en din er av største betydning for å sikre at API-et vil forbli kompatibel med alle klientene som bruker det. Denne artikkelen presenterer en diskusjon om hvordan du kan opprettholde bakoverkompatibilitet i dine RESTful APIer.

API-kompatibilitetseksempel

Anta at du har et API i produksjon som forbrukes av forskjellige klienter. Nå hvis du vil legge til mer funksjonalitet i API-en, bør du sørge for at klientene som bruker den gamle API-en, kan bruke enten den nye eller den gamle API-en. Med andre ord, bør du sørge for at den eksisterende funksjonaliteten til API-en forblir intakt mens den nye funksjonaliteten blir lagt til.

En API er bakoverkompatibel hvis en klient (et program skrevet for å konsumere API) som kan fungere med en versjon av API, kan fungere på samme måte med fremtidige versjoner av API. Med andre ord er en API bakoverkompatibel mellom utgivelser hvis klientene skal kunne jobbe med en ny versjon av API sømløst.

La oss forstå dette med et eksempel. Anta at du har en API-metode kalt GetOrders som vist i kodebiten nedenfor.

[HttpGet]

[Rute ("GetOrders")]

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

 {

var result = _orderService.GetOrdersForCustomer (

customerId, orderId);

returner Ok (resultat);

 }

Handlingsmetoden GetOrders godtar en kunde-ID og en bestillings-ID som parametere. Merk at den andre parameteren, orderID, er valgfri. GetOrdersForCustomer private metode er gitt nedenfor.

privat liste GetOrdersForCustomer (int customerId, int orderId)

{

// Skriv kode her for å returnere en eller flere ordreoppføringer

}

GetOrdersForCustomer-metoden returnerer alle bestillinger fra en kunde hvis orderId ble sendt til den som en parameter er 0. Hvis orderId ikke er null, returnerer den en ordre som gjelder kunden identifisert av customerId sendt som et argument.

Siden den andre parameteren til GetOrders-handlingsmetoden er valgfri, kan du bare passere customerId. Nå, hvis du endrer den andre parameteren for handlingsmetoden GetOrders for å gjøre det obligatorisk, vil ikke de gamle klientene til API-et lenger kunne bruke API-en.

[HttpGet]

[Rute ("GetOrders")]

offentlige IActionResult GetOrders (int customerId, int orderId)

 {

var result = _orderService.GetOrdersForCustomer

(customerId, orderId);

returner Ok (resultat);

 }

Og det er akkurat slik du kan bryte kompatibiliteten til API-en din! Avsnittet som følger diskuterer de beste metodene som kan brukes for å gjøre API-en din bakoverkompatibel.

API-kompatibilitetstips

Nå som vi vet hva problemet handler om, hvordan designer vi APIene våre på den anbefalte måten? Hvordan sikrer vi at vår RESTful API er bakoverkompatibel? Denne delen lister opp noen av de beste metodene som kan følges i denne forbindelse.

Forsikre deg om at enhetstestene består

Du bør ha skrevet tester som vil verifisere om funksjonaliteten er intakt med en ny versjon av API. Testene skal skrives på en slik måte at de skulle mislykkes hvis det er problemer med bakoverkompatibilitet. Ideelt sett bør du ha en testpakke for API-testing som mislykkes og varsler når det er problemer med bakoverkompatibilitet til API. Du kan også ha en automatisk testpakke koblet til CI / CD-rørledningen som sjekker for bakoverkompatibilitet og varsler når det er et brudd.

Endre aldri oppførselen til HTTP-responskoder

Du bør aldri endre atferden til HTTP-responskoder i API-et ditt. Hvis API-en din returnerer 500 når den ikke klarer å koble til databasen, bør du ikke endre den til 200. På samme måte, hvis du returnerer HTTP 404 når et unntak oppstår, og klientene bruker dette og svarobjektet for å identifisere hva som gikk feil, å endre denne API-metoden for å returnere HTTP 200 vil bryte bakoverkompatibiliteten helt.

Endre aldri parametere

Unngå å lage en ny versjon av API når du bare gjør mindre endringer, da det kan være for mye. En bedre tilnærming er å legge til parametere i API-metodene dine for å innlemme den nye atferden. På samme måte bør du ikke fjerne parametere fra en API-metode eller endre en parameter fra valgfri til obligatorisk (eller omvendt), da disse endringene vil bryte API-en og gamle klienter eller forbrukere av API-en ikke lenger vil være i stand til å jobbe med API.

Versjon API-et ditt

Versjonering av API-er er god praksis. Versjonering hjelper deg med å gjøre API-et ditt mer fleksibelt og tilpasse seg endringer mens du holder funksjonaliteten intakt. Det hjelper deg også med å administrere endringer i koden bedre og lettere gå tilbake til gammel kode hvis den nye koden gir problemer. Du bør ha en annen versjon av RESTful API for hver større utgivelse.

Selv om REST ikke gir noen spesifikk veiledning om API-versjonering, kan du versjonere API-en din på tre forskjellige måter: spesifisere versjonsinformasjonen i URI, lagre versjonsinformasjonen i den tilpassede forespørselstittelen og legge til versjonsinformasjonen i HTTP-godkjennelsen Overskrift. Selv om versjonering kan hjelpe deg med å vedlikeholde API-en, bør du unngå å prøve å vedlikeholde mange versjoner av API-et for å markere hyppige utgivelser. Dette vil fort bli tungvint og kontraproduktivt.

Andre API-fremgangsmåter

Du bør aldri endre rot-URL-en til et API eller endre de eksisterende spørringsstrengparametrene. Eventuell tilleggsinformasjon bør legges til som en valgfri parameter til en API-metode. Du bør også sørge for at valgfrie eller obligatoriske elementer som sendes til en API eller returneres fra en API aldri blir slettet.

Endringer i en RESTful API er uunngåelig. Imidlertid, med mindre du følger de beste fremgangsmåtene og sørger for at API-en er bakoverkompatibel, kan endringene dine bryte API-ens kompatibilitet med eksisterende klienter. En API som er i produksjon og blir konsumert av flere klienter, bør alltid være bakoverkompatibel mellom utgivelser.

$config[zx-auto] not found$config[zx-overlay] not found