Reprezentatīvā stāvokļa pārsūtīšana, ko parasti sauc par REST, ir arhitektūras stils - ierobežojumu kopums, ko izmanto, lai ieviestu bezvalstnieku pakalpojumus, kas darbojas ar HTTP. RESTful API ir tāds, kas atbilst REST ierobežojumiem. Jūs varat izveidot RESTful API, izmantojot daudzas dažādas programmēšanas valodas.
Atkārtotas savietojamības saglabāšana starp dažādiem jūsu API laidieniem ir ārkārtīgi svarīga, lai nodrošinātu, ka jūsu API paliks saderīga ar visiem klientiem, kuri to lieto. Šajā rakstā ir sniegta diskusija par to, kā saglabāt savietojamību savās RESTful API.
API saderības piemērs
Pieņemsim, ka jums ir API ražošanā, kuru patērē dažādi klienti. Tagad, ja vēlaties pievienot vairāk funkcionalitātes API, jums jāpārliecinās, ka klienti, kas izmanto veco API, varēs izmantot vai nu jauno, vai veco. Citiem vārdiem sakot, jums jānodrošina, ka esošā API funkcionalitāte paliks neskarta, kamēr tiks pievienota jaunā funkcionalitāte.
API ir savietojams ar atpakaļejošu datumu, ja klients (programma, kas rakstīta API patēriņam), kas var strādāt ar vienu API versiju, var darboties tāpat kā nākamās API versijas. Citiem vārdiem sakot, API ir atpakaļejoši savietojams ar laidieniem, ja klientiem ir jāspēj nemanāmi strādāt ar jaunu API versiju.
Sapratīsim to ar piemēru. Pieņemsim, ka jums ir API metode ar nosaukumu GetOrders, kā parādīts zemāk esošajā koda fragmentā.
[HttpGet][Maršruts ("GetOrders")]
public IActionResult GetOrders (int customerId, int orderId = 0)
{
var result = _orderService.GetOrdersForCustomer (
customerId, orderId);
atgriezties Ok (rezultāts);
}
GetOrders darbības metode kā parametrus pieņem klienta ID un pasūtījuma ID. Ņemiet vērā, ka otrais parametrs orderID nav obligāts. Privātā metode GetOrdersForCustomer ir dota tālāk.
privāts saraksts GetOrdersForCustomer (int customerId, int orderId){
// Šeit ierakstiet kodu, lai atgrieztu vienu vai vairākus pasūtījumu ierakstus
}
Metode GetOrdersForCustomer atgriež visus klienta pasūtījumus, ja tam kā parametrs nodotais orderId ir 0. Ja orderId nav nulle, tas atgriež vienu pasūtījumu, kas attiecas uz klientu, kuru klients identificējis kā argumentu.
Tā kā GetOrders darbības metodes otrais parametrs nav obligāts, varat vienkārši nodot klienta ID. Ja tagad mainīsit darbības metodes GetOrders otro parametru, lai tas būtu obligāts, vecie API klienti vairs nevarēs izmantot API.
[HttpGet][Maršruts ("GetOrders")]
public IActionResult GetOrders (int customerId, int orderId)
{
var result = _orderService.GetOrdersForCustomer
(klienta ID, pasūtījuma ID);
atgriezties Ok (rezultāts);
}
Un tieši tā jūs varat pārtraukt API savietojamību! Turpmākajā sadaļā ir apspriesta paraugprakse, ko var izmantot, lai padarītu jūsu API atpakaļ savietojamu.
API saderības padomi
Tagad, kad mēs zinām, kāda ir problēma, kā mēs veidojam mūsu API ieteicamo veidu? Kā mēs nodrošinām, ka mūsu RESTful API ir savietojama ar atpakaļejošu datumu? Šajā sadaļā ir uzskaitītas dažas labākās prakses, kuras šajā sakarā var ievērot.
Pārliecinieties, ka vienības testi ir izturēti
Jums vajadzētu būt uzrakstītiem testiem, kas pārbaudīs, vai funkcionalitāte ir neskarta ar jaunu API laidienu. Pārbaudes jāraksta tādā veidā, ka tās neizdodas, ja rodas kādas saderības problēmas ar atpakaļejošu datumu. Ideālā gadījumā jums vajadzētu būt testēšanas komplektam API testēšanai, kas neizdosies un brīdinās, ja rodas problēmas ar API savietojamību atpakaļ. CI / CD cauruļvadā var būt arī pievienots automatizēts testu komplekts, kas pārbauda savietojamību ar atpakaļejošu brīdinājumu un brīdina, ja ir pārkāpums.
Nekad nemainiet HTTP atbildes kodu darbību
Nekad nevajadzētu mainīt HTTP atbildes kodu darbību savā API. Ja jūsu API atgriež 500, kad neizdodas izveidot savienojumu ar datu bāzi, nevajadzētu to mainīt uz 200. Līdzīgi, ja atgriežat HTTP 404, kad rodas izņēmums, un klienti izmanto šo un atbildes objektu, lai identificētu, kas notika nepareizi, mainot šo API metodi, lai atgrieztu HTTP 200, tā pilnībā sadrumstalotu.
Nekad nemainiet parametrus
Veicot tikai nelielas izmaiņas, izvairieties no jaunas API versijas izveides, jo tā var būt pārspīlēta. Labāka pieeja ir parametru pievienošana API metodēm, lai iekļautu jauno rīcību. Tādā pašā veidā nevajadzētu noņemt parametrus no API metodes vai mainīt parametru no izvēles uz obligātu (vai otrādi), jo šīs izmaiņas izjauks API un vecie klienti vai API klienti vairs nevarēs strādāt ar API.
Verificējiet savu API
API versija ir laba prakse. Versija palīdz padarīt jūsu API elastīgāku un pielāgojamāku izmaiņām, vienlaikus saglabājot funkcionalitāti neskartu. Tas arī palīdz labāk pārvaldīt koda izmaiņas un vieglāk atgriezties pie vecā koda, ja jaunais kods rada problēmas. Katram galvenajam laidienam jums vajadzētu būt savai RESTful API atšķirīgai versijai.
Neskatoties uz to, ka REST nesniedz nekādas īpašas vadlīnijas par API versiju veidošanu, varat versiju izveidot trīs dažādos veidos: norādot versijas informāciju URI, saglabājot versijas informāciju pielāgotā pieprasījuma galvenē un pievienojot versijas informāciju HTTP Accept galveni. Lai gan versiju veidošana var palīdzēt uzturēt jūsu API, jums nevajadzētu mēģināt uzturēt daudzas API versijas, lai atzīmētu biežus izlaidumus. Tas ātri kļūs apgrūtinošs un neproduktīvs.
Cita API paraugprakse
Nekad nevajadzētu mainīt API saknes URL vai modificēt esošos vaicājuma virknes parametrus. Jebkura papildu informācija jāpievieno kā izvēles parametrs API metodei. Jums arī jānodrošina, lai izvēles vai obligātie elementi, kas tiek nodoti API vai tiek atgriezti no API, nekad netiktu izdzēsti.
RESTful API izmaiņas ir neizbēgamas. Tomēr, ja neievērosiet paraugpraksi un nenodrošināsiet, ka API ir savietojama ar atpakaļejošu datumu, jūsu veiktās izmaiņas var sabojāt API saderību ar esošajiem klientiem. API, kas tiek ražota un kuru patērē vairāki klienti, vienmēr būtu jāatbalsta starp laidieniem atpakaļ.
