Kako vaše REST API-je učiniti unatrag kompatibilnima

Reprezentativni prijenos države, poznat i pod nazivom REST, arhitektonski je stil - skup ograničenja koja se koriste za implementaciju usluga bez državljanstva koje se izvode na HTTP-u. RESTful API je onaj koji je u skladu s REST ograničenjima. Možete graditi RESTful API-je koristeći mnogo različitih programskih jezika.

Održavanje povratne kompatibilnosti između različitih izdanja vašeg API-ja od najveće je važnosti kako bi se osiguralo da će vaš API ostati kompatibilan sa svim klijentima koji ga koriste. Ovaj članak predstavlja raspravu o tome kako možete zadržati povratnu kompatibilnost u svojim RESTful API-ima.

Primjer kompatibilnosti API-ja

Pretpostavimo da imate API u proizvodnji koji koriste različiti klijenti. Sada ako želite dodati više funkcionalnosti API-ju, trebali biste osigurati da će klijenti koji koriste stari API moći koristiti novi ili stari API. Drugim riječima, trebali biste osigurati da postojeća funkcionalnost API-ja ostane netaknuta dok se doda nova funkcionalnost.

API je kompatibilan s unatrag ako klijent (program napisan za konzumiranje API-ja) koji može raditi s jednom verzijom API-ja može raditi na isti način sa budućim verzijama API-ja. Drugim riječima, API je unatrag kompatibilan između izdanja ako bi klijenti mogli nesmetano raditi s novom verzijom API-ja.

Shvatimo to na primjeru. Pretpostavimo da imate API metodu koja se zove GetOrders kao što je prikazano u isječku koda u nastavku.

[HttpGet]

[Ruta ("GetOrders")]

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

 {

   rezultat rezultata = _orderService.GetOrdersForCustomer (

                 customerId, orderId);

   povratak Ok (rezultat);

 }

Metoda akcije GetOrders prihvaća ID kupca i ID narudžbe kao parametre. Imajte na umu da drugi parametar, orderID, nije obavezan. Privatna metoda GetOrdersForCustomer dana je u nastavku.

privatni popis GetOrdersForCustomer (int customerId, int orderId)

{

   // Ovdje napišite kod za povratak jednog ili više zapisa narudžbe

}

Metoda GetOrdersForCustomer vraća sve narudžbe kupca ako joj je orderId proslijeđen kao parametar 0. Ako orderId nije nula, vraća jednu narudžbu koja se odnosi na kupca identificiranog od customerId prosljeđenog kao argument.

Budući da je drugi parametar metode akcije GetOrders neobavezan, možete samo proslijediti customerId. Sada, ako promijenite drugi parametar akcijske metode GetOrders kako bi bio obvezan, stari klijenti API-ja više neće moći koristiti API.  

[HttpGet]

[Ruta ("GetOrders")]

 javni IActionResult GetOrders (int customerId, int orderId)

 {

   var rezultat = _orderService.GetOrdersForCustomer

                 (customerId, orderId);

   povratak Ok (rezultat);

 }

I upravo tako možete prekinuti kompatibilnost svog API-ja! Sljedeći odjeljak raspravlja o najboljim praksama koje se mogu usvojiti kako bi vaš API bio kompatibilan s unatrag.

Savjeti za kompatibilnost API-ja

Sad kad znamo u čemu je problem, kako dizajnirati naše API-je na preporučeni način? Kako osiguravamo da je naš RESTful API kompatibilan s unatrag? Ovaj odjeljak navodi neke od najboljih praksi koje se u tom pogledu mogu slijediti. 

Provjerite jesu li jedinični testovi prošli

Trebali biste imati napisane testove koji će s novim izdanjem API-ja provjeriti je li funkcionalnost netaknuta. Testovi bi trebali biti napisani na takav način da ne bi uspjeli ako postoje problemi s povratnom kompatibilnošću. Idealno bi bilo da imate testni paket za API testiranje koji neće uspjeti i upozorit će kada postoje problemi s povratnom kompatibilnošću API-ja. Mogli biste imati i automatizirani paket za testiranje priključen na CI / CD cjevovod koji provjerava povratnu kompatibilnost i upozorenja kada postoji kršenje.

Nikada ne mijenjajte ponašanje HTTP kodova odgovora

Nikada ne biste trebali mijenjati ponašanje HTTP kodova odgovora u svom API-ju. Ako vaš API vrati 500 kad se ne uspije povezati s bazom podataka, ne biste ga trebali promijeniti na 200. Slično tome, ako HTTP 404 vraćate kada se dogodi iznimka, a vaši klijenti koriste ovo i objekt odgovora da identificiraju što je prošlo pogrešno, promjena ove API metode za vraćanje HTTP 200 u potpunosti će prekinuti povratnu kompatibilnost.

Nikada ne mijenjajte parametre

Izbjegavajte stvaranje nove verzije API-ja kada unosite samo manje izmjene, jer bi to moglo biti pretjerano. Bolji pristup je dodavanje parametara u vaše API metode kako bi se ugradilo novo ponašanje. Po istom principu, ne biste trebali uklanjati parametre iz API metode ili mijenjati parametar iz neobaveznog u obvezni (ili obrnuto), jer će te promjene prekinuti API i stari klijenti ili potrošači API-ja više neće moći za rad s API-jem.

Verzija vašeg API-ja

Izrada verzija API-ja dobra je praksa. Izrada verzija pomaže vam da vaš API postane fleksibilniji i prilagodljiviji promjenama, a funkcionalnost ostaje netaknuta. Također vam pomaže da bolje upravljate promjenama koda i lakše se vratite na stari kôd ako novi kôd stvara probleme. Uz svako veće izdanje trebali biste imati drugačiju verziju API-ja RESTful.

Iako REST ne pruža nikakve posebne smjernice za izradu verzija API-ja, svoj API možete verzijati na tri različita načina: specificiranjem podataka o verziji u URI-ju, pohranjivanjem podataka o verziji u zaglavlje prilagođenog zahtjeva i dodavanjem podataka o verzijama u HTTP Accept Zaglavlje. Iako vam inačice verzija mogu pomoći u održavanju API-ja, trebali biste izbjegavati pokušaje održavanja mnogih verzija API-ja kako biste obilježili česta izdanja. To će brzo postati glomazno i ​​kontraproduktivno. 

Ostale najbolje prakse za API

Nikada ne biste trebali mijenjati korijenski URL API-ja ili mijenjati postojeće parametre niza upita. Sve dodatne informacije treba dodati kao neobavezni parametar API metodi. Također biste trebali osigurati da se neobavezni ili obvezni elementi koji se prosljeđuju API-ju ili se vraćaju iz API-ja nikada ne brišu.

Promjene RESTful API-ja su neizbježne. Međutim, ako se ne pridržavate najboljih praksi i ne osigurate da je API unatrag kompatibilan, vaše promjene mogu prekinuti kompatibilnost API-ja s postojećim klijentima. API koji je u proizvodnji i koji ga koristi više klijenata uvijek bi trebao biti unatrag kompatibilan između izdanja.