API versijų gairės?

Ar yra žinomų žiniatinklio paslaugų REST API versijos valdymo instrukcijų ar gairių?

Pastebėjau, kad AWS atlieka versijos kontrolę galutinio taško URL . Ar tai vienintelis būdas ar yra kitų būdų pasiekti tą patį tikslą? Jei yra keletas būdų, kokie yra kiekvieno privalumai?

878
23 дек. nustatė „ Swaroop CH 23“. 2008-12-23 18:32 '08 at 18:32 2008-12-23 18:32
@ 7 atsakymai

Tai geras ir sudėtingas klausimas. URI dizaino tema tuo pačiu metu yra svarbiausia REST API dalis , todėl galbūt ilgalaikis įsipareigojimas šio API naudotojams .

Nuo paraiškos evoliucijos ir, mažesniu mastu, jos API yra gyvenimo faktas ir netgi panašus į tariamai sudėtingo produkto, pvz., Programavimo kalbos, raidą, URI dizainas turėtų turėti mažiau natūralių apribojimų ir turėtų išlikti laikui bėgant . Kuo ilgesnis programų ir API naudojimo laikas, tuo didesnis įsipareigojimo taikymas programos naudotojams ir API.

Kita vertus, kitas gyvenimo faktas yra tai, kad sunku numatyti visus išteklius ir jų aspektus, kurie bus vartojami per API. Laimei, nėra reikalo sukurti visą API, kuri bus naudojama prieš Apokalipsę . Pakanka teisingai identifikuoti visus išteklių šaltinius ir kiekvienos išteklių šaltinio adresavimo schemą.

Laikui bėgant, gali prireikti pridėti naujų išteklių ir naujų atributų kiekvienam konkrečiam ištekliui, tačiau metodas, kurį API naudotojai naudoja tam tikriems ištekliams pasiekti, neturėtų keistis po to, kai išteklių adresavimo schema yra viešai prieinama ir todėl galutinis.

Šis metodas taikomas „HTTP“ veiksmažodžio semantikai (pavyzdžiui, PUT turėtų visada atnaujinti / pakeisti) ir HTTP būsenos kodais, kurie yra palaikomi ankstesnėse API versijose (jie turi toliau dirbti, kad API klientai, dirbantys be žmogaus įsikišimo, galėtų toliau dirbti tokiu būdu) ).

Be to, kadangi API versijos įterpimas į URI pažeidžia hipermedijos, kaip taikomosios programos variklio, sąvoką (nurodyta Roy T. Fielding PhD), turint omenyje išteklių / URI adresą, kuris laikui bėgant keičiasi, galiu daryti išvadą, kad API versijos neturėtų būti saugomos išteklių URI ilgą laiką , o tai reiškia, kad išteklių URI, kuriuos API naudotojai gali priklausyti, turėtų būti permalinkai .

Žinoma, galite įterpti API versiją į pagrindinį URI , bet tik pagrįstai ir ribotai naudoti, pavyzdžiui, API kliento, kuris dirba su nauja API versija, derinimui. Tokia API su versijomis turėtų būti ribota laiku ir prieinama tik ribotoms API naudotojų grupėms (pvz., Uždaroms beta versijoms). Priešingu atveju pasižadate, kur neturėtumėte.

Keletas minčių apie API versijų priežiūrą, kurių galiojimas jiems yra. Visos programavimo platformos / kalbos, dažniausiai naudojamos interneto paslaugoms diegti („Java“, „.NET“, „PHP“, „Perl“, „Rails“ ir kt.), Leidžia lengvai susieti žiniatinklio paslaugų galinius taškus su pagrindiniu URI. Taigi, lengva rinkti ir išsaugoti rinkmenas / klases / metodus skirtingose ​​API versijose .

POV API naudotojams taip pat lengviau dirbti su tam tikra API versija ir prisijungti prie konkrečios API versijos, kai tai akivaizdi, bet tik ribotą laiką, ty kūrimo metu.

API, POV API yra lengviau išlaikyti skirtingas API versijas lygiagrečiai naudojant versijų valdymo sistemas, kurios dažniausiai veikia su failais kaip mažiausiu vienetu (šaltinio kodo versijomis).

Tačiau su API versijomis, kurios yra gerai matomos URI, yra įspėjimas: taip pat galite prieštarauti šiam požiūriui, nes API istorija tampa matoma / aparent URI dizaine , todėl laikas gali keistis , o tai prieštarauja REST rekomendacijoms. Sutinku!

Kaip pasiekti šį protingą prieštaravimą yra įdiegti naujausią API versiją neaktyvios API URI duomenų bazėje. Tokiu atveju API kliento kūrėjai gali pasirinkti:

  • vystosi prieš tai (įsipareigojimas paremti programą, kuri apsaugo ją nuo galimų API pakeitimų, kurie gali sutrikdyti jų prastą kliento dizainą ).

  • privaloma taikyti tam tikrą API versiją (kuri tampa akivaizdi), bet tik ribotą laiką

Pavyzdžiui, jei v3.0 API yra naujausia API versija, šie du turėtų būti slapyvardžiai (pvz., Elgtis taip pat su visais API užklausomis):

  http: // shonzilla / api / customers / 1234 http: // shonzilla / api /v3.0 / customers / 1234 http: // shonzilla / api / v3 / customers / 1234

Be to, API klientams, kurie vis dar bando atkreipti dėmesį į senąją API, turėtų būti pranešta apie naujausios ankstesnės API versijos naudojimą, jei naudojamo API versija yra pasenusi arba nebepalaikoma . Taigi, prieigą prie bet kurio pasenusio URI, pvz .:

 http: // shonzilla / api /v2.2 / customers / 1234 http: // shonzilla / api /v2.0 / customers / 1234 http: // shonzilla / api / v2 / customers / 1234 http: // shonzilla / api /v1.1 / customers / 1234 http: // shonzilla / api / v1 / customers / 1234

privalo grąžinti bet kurį HTTP 30x būsenos kodą , nurodantį nukreipimą , kuris naudojamas kartu su HTTP Location antrašte, kuris nukreipia į atitinkamą išteklių URI versiją, kuri lieka tokia pati:

  http: // shonzilla / api / customers / 1234

Yra bent du HTTP peradresavimo būsenos kodai, tinkami API versijos valdymo scenarijai:

  • 301 Nuolat juda , nurodydama, kad išteklius su prašomu URI yra nuolat perkeliamas į kitą URI (kuris turi būti nuolatinė išteklių, kurios sudėtyje nėra API versijos, egzemplioriaus vertė). Šis būsenos kodas gali būti naudojamas norint nustatyti pasenusią / nepalaikomą API versiją, kuri informuoja API klientą apie ištekliaus išteklių versijos pakeitimą permalink išteklių nuoroda .

  • 302 Rasta , nurodant, kad prašomas išteklius laikinai yra kitur, o prašomas URI vis tiek gali būti palaikomas. Šis būsenos kodas gali būti naudingas, kai ne versijuotas URI laikinai nepasiekiamas ir prašymas turėtų būti pakartotas naudojant peradresavimo adresą (pvz., Nukreipiant į URI su įterptą APi versiją) ir norime pasakyti klientams, kad jie ir toliau naudotųsi (pvz., „Permalinks“) .

  • kitus scenarijus galima rasti 3 skyriuje peradresavimu HTTP 1.1 specifikacijoje

685
29 дек. atsakymą pateikė Shonzilla 29 d. 2008-12-29 23:24 '09, 23:24, 2008-12-29 23:24

URL neturi būti versijų. Versija neturi nieko bendro su prašomo išteklių „idėja“. Turėtumėte pabandyti pateikti URL kaip norimą koncepciją, o ne kaip grąžinti elementą. Versija diktuoja objekto, o ne objekto sąvokos vaizdą. Kaip sakė kiti plakatai, prašymo antraštėje turite nurodyti formatą (įskaitant versiją).

Jei peržiūrite visą HTTP užklausą dėl URL, turinčių versijų, tai atrodo taip:

 (BAD WAY TO DO IT): http://company.com/api/v3.0/customer/123 ====> GET v3.0/customer/123 HTTP/1.1 Accept: application/xml <==== HTTP/1.1 200 OK Content-Type: application/xml <customer version="3.0"> <name>Neil Armstrong</name> </customer> 

Antraštėje yra eilutė, kurioje yra prašomas vaizdas („Accept: application / xml“). Būtent čia turėtų eiti versija. Atrodo, kad kiekvienas tylėjo apie tai, kad galbūt norėsite to paties dalyko įvairiais formatais ir kad klientas turėtų galėti paklausti, ko jis nori. Pirmiau pateiktame pavyzdyje klientas prašo XML ANY XML reprezentacijos, o ne tikrojo reprezentacijos, ko nori. Teoriškai serveris galėtų grąžinti kažką visiškai nesusijusio su prašymu, jei jis būtų XML, ir jį reikėtų analizuoti, kad suprastumėte, jog tai neteisinga.

Geriausias būdas:

 (GOOD WAY TO DO IT) http://company.com/api/customer/123 ===> GET /customer/123 HTTP/1.1 Accept: application/vnd.company.myapp.customer-v3+xml <=== HTTP/1.1 200 OK Content-Type: application/vnd.company.myapp-v3+xml <customer> <name>Neil Armstrong</name> </customer> 

Tada, tarkim, klientai mano, kad XML yra pernelyg žodžio, ir dabar jiems reikia JSON. Kituose pavyzdžiuose turi būti naujas URL to paties kliento, todėl gausite:

border=0
 (BAD) http://company.com/api/JSONv3.0/customers/123 or http://company.com/api/v3.0/customers/123?format="JSON" 

(arba kažkas panašaus). Kai iš tikrųjų, kiekviename HTTP užklausoje yra formatas, kurio ieškote:

 (GOOD WAY TO DO IT) ===> GET /customer/123 HTTP/1.1 Accept: application/vnd.company.myapp.customer-v3+json <=== HTTP/1.1 200 OK Content-Type: application/vnd.company.myapp-v3+json {"customer": {"name":"Neil Armstrong"} } 

Naudodami šį metodą, turite daug daugiau laisvės dizaino srityje ir iš tikrųjų laikosi pradinės „REST“ idėjos. Galite keisti versijas netrikdydami klientų arba palaipsniui pakeiskite klientus, kai API keičiasi. Jei nuspręsite nepalaikyti rodinio, galite atsakyti į užklausas su HTTP būsenos kodu arba specialiais kodais. Klientas taip pat gali patikrinti, ar atsakymas yra teisingas, ir patikrinkite XML.

Yra daug kitų privalumų, ir kai kuriuos iš jų aptarsiu savo dienoraštyje: http://thereisnorightway.blogspot.com/2011/02/versioning-and-types-in-resthttp-api.html

Paskutinis pavyzdys rodo, kaip blogai versija perkeliama į URL. Tarkime, kad jums reikia informacijos, esančios objekte, ir patikrinote įvairius objektus (klientai v3.0, užsakymai v2.0 ir laivo objektas v4.2). Čia yra bjaurus URL, kurį reikia nurodyti kliente:

 (Another reason why version in the URL sucks) http://company.com/api/v3.0/customer/123/v2.0/orders/4321/ 
273
19 июля '11 в 19:08 2011-07-19 19:08 atsakymas duotas jeremyh 19 liepa, 11 val. 19:08 2011-07-19 19:08

Mes nustatėme, kad praktiška ir naudinga patalpinti versiją į URL. Tai leidžia lengvai suprasti, ką naudojate iš pirmo žvilgsnio. Naudojame slapyvardį / foo / foo / (naujausias versijas) naudojimui, trumpesniems / švaresniems URL ir tt, kaip rodo priimtas atsakymas.

Nuolatinio suderinamumo išlaikymas amžinai dažnai yra brangus ir (arba) labai sudėtingas. Mes norėtume iš anksto pranešti apie pasenusius, nukreipimus, dokumentus ir kitus čia siūlomus mechanizmus.

99
04 янв. atsakymą pateikė Yoav Shapira 04 Jan 2011-01-04 23:57 '11 ne 23:57 2011-01-04 23:57

Sutinku, kad teisingas išteklių pateikimas geriau tinka REST metodui ... bet viena didelė problema su pasirinktiniais MIME tipais (arba MIME tipais, pridedančiais versijos parametrą) yra prasta parama rašant „Accept“ ir „Turinio tipo“ antraštes HTML ir „JavaScript“ .

Pvz., Neįmanoma sukurti IMO POST sistemai su šiais HTML5 antraštėmis, kad sukurtumėte šaltinį:

 Accept: application/vnd.company.myapp-v3+json Content-Type: application/vnd.company.myapp-v3+json 

Taip yra dėl to, kad HTML5 enctype atributas yra skaičiavimas, todėl nieko, išskyrus įprastą application/x-www-formurlencoded , multipart/form-data ir text/plain nėra.

... ir esu įsitikinęs, kad jis yra palaikomas visose HTML4 naršyklėse (kuri turi silpnesnį encytpe atributą, bet bus su naršyklės diegimu susijusi problema, ar MIME tipas buvo peradresuotas)

Todėl dabar manau, kad tinkamiausias būdas versijai yra per URI, bet sutinku, kad tai nėra „teisingas“ būdas.

46
13 окт. Kevyčio atsakymas spalio 13 d 2011-10-13 13:51 '11, 13:51 pm, 2011-10-13 13:51

Įdėkite savo versiją į URI. Viena API versija ne visada palaiko tipus iš kitos, todėl argumentas, kad ištekliai tiesiog perkeliami iš vienos versijos į kitą, yra tiesiog neteisingas. Tai ne tas pats, kaip formato keitimas iš XML į JSON. Tipai gali nebūti, arba juos galima keisti semantiškai.

Variantai yra išteklių adreso dalis. Jūs nukreipiate iš vienos API į kitą. Negalima paslėpti adresų antraštėje.

21
05 июня '12 в 18:09 2012-06-05 18:09 atsakymas Seanui O'Dellui birželio 12 d. 12 val. 2012-06-05 18:09

Yra kelios vietos, kuriose galite valdyti versijas „REST“ API:

  • Kaip pažymėta URI. Tai gali būti priimtina ir netgi estetiškai patraukli, jei peradresavimai ir pan. Naudojamas gerai.

  • Antraštėje „Priimti“ patvirtinkite, kad versija yra faile. Kaip „mp3“, palyginti su „mp4“. Tai taip pat veiks, nors TJO veikia šiek tiek blogiau nei ...

  • Pats išteklius. Daug failų formatų yra įterpti jų versijos numeriai, paprastai antraštėje; tai leidžia naujesnei programinei įrangai „tiesiog dirbti“, suprantant visas esamas failo tipo versijas, o senesnė programinė įranga gali būti naudojama, jei nurodoma nepalaikoma (naujesnė) versija. REST API kontekste tai reiškia, kad jūsų URI niekada neturėtų keistis, tik jūsų atsakymas į konkrečią jūsų perduotų duomenų versiją.

Matau priežasčių naudoti visus tris metodus:

  • jei norite naudoti naujas švarias „sweep“ API arba keisti pagrindinius versijas, kur norite naudoti šį metodą.
  • jei norite, kad klientas žinotų prieš atlikdamas PUT / POST, ar jis veiks, ar ne.
  • jei viskas yra gerai, jei klientas turi atlikti PUT / POST, kad pamatytų, ar jis veiks.
13
24 окт. atsakymas pateikiamas pjz 24 oct. 2011-10-24 19:39 '11, 19:39, 2011-10-24 19:39

„REST API“ versijos yra tokios pačios kaip bet kuri kita API. Nedidelius pakeitimus galima atlikti vietoje, todėl pagrindiniams pakeitimams gali prireikti visiškai naujos API. Paprasčiausias jums yra pradėti nuo nulio kiekvieną kartą, kai įdiegiate versiją URL yra prasminga. Jei norite palengvinti kliento gyvenimą, bandote išlaikyti atgalinį suderinamumą, kurį galite padaryti su pasenusiu (nuolatiniu peradresavimu), ištekliais keliomis versijomis ir kt. Tai sunkiau ir reikalauja daugiau pastangų. Bet tai taip pat yra tai, ką REST rekomenduoja „Cool URIs“, nekeiskite.

Galų gale jis atrodo kaip bet kuris kitas API dizainas. Pasverkite pastangas prieš klientų patogumą. Pagalvokite apie tai, kaip naudoti semantinę savo API versiją, leidžiant klientams suprasti, kaip suderinama jūsų nauja versija.

8
06 марта '14 в 10:16 2014-03-06 10:16 Atsakymą davė Aleksandras Torstlingas kovo 6 d. 14 d. 10:16 2014-03-06 10:16

Kiti klausimai apie žymes arba Užduoti klausimą