streamalism.org

1. Problém

Vývoj rozhrania REST API je zložitý problém - pre ktorý je k dispozícii veľa možností. Tento článok pojednáva o niektorých z týchto možností.

2. Čo je v zmluve?

Predtým si musíme odpovedať na jednu jednoduchú otázku: Aká je zmluva medzi API a Zákazník?

2.1. Identifikátory URI sú súčasťou zmluvy?

Najprv zvážime štruktúra URI rozhrania REST API - je to súčasť zmluvy? Mali by si klienti ukladať záložky, pevné kódy a všeobecne sa spoliehať na URI API?

V takom prípade by potom interakcia Klienta so Službou REST už nebola riadená samotnou Službou, ale tým, čo volá Roy Fielding von zo skupiny informácie:

Rozhranie REST API by malo byť zadané bez akýchkoľvek predchádzajúcich znalostí okrem počiatočného identifikátora URI (záložky) a sady štandardizovaných typov médií, ktoré sú vhodné pre zamýšľané publikum ... Zlyhanie tu znamená, že informácie mimo pásma riadia interakciu namiesto hypertextu.

Tak jasne URI nie sú súčasťou zmluvy! Klient by mal poznať iba jeden URI - vstupný bod do API. Všetky ostatné identifikátory URI by sa mali odhaliť počas konzumácie API.

2.2. Druhy médií, ktoré sú súčasťou zmluvy?

Ako je to s informáciami o type média použitými na znázornenie zdrojov - sú to súčasť zmluvy medzi klientom a službou?

Pre úspešné využitie API musí byť Klient oboznámený s týmito typmi médií. Definícia týchto typov médií v skutočnosti predstavuje celú zmluvu.

Na toto by sa preto mala služba REST zamerať najviac:

Rozhranie REST API by malo vynaložiť takmer všetko svoje popisné úsilie na definovanie typov médií, ktoré sa používajú na reprezentáciu zdrojov a riadenie stavu aplikácie, alebo na definovanie rozšírených názvov vzťahov a / alebo prirážok s hypertextom pre existujúce štandardné typy médií.

Takže Definície typu média sú súčasťou zmluvy a mali by to byť predchádzajúce znalosti pre klienta, ktorý používa API. Tu prichádza na rad štandardizácia.

Teraz máme dobrú predstavu o tom, o akú zmluvu sa jedná. Prejdime k tomu, ako skutočne vyriešiť problém s verziou.

3. Možnosti na vysokej úrovni

Poďme teraz diskutovať o prístupoch na vysokej úrovni k verzovaniu REST API:

• Správa verzií URI - verzia priestoru URI pomocou indikátorov verzie
• Správa verzií typu média - verzia Zastúpenie zdroja

Keď uvedieme verziu v priestore URI, reprezentácie zdrojov sa považujú za nemenné. Takže keď je potrebné zaviesť zmeny v API, je potrebné vytvoriť nový priestor URI.

Napríklad povedzme, že API zverejňuje nasledujúce zdroje - používateľov a oprávnenia:

// hostiteľ / v1 / používatelia // hostiteľ / v1 / oprávnenie

Teraz si vezmime, že prelomová zmena v používateľov API vyžaduje zavedenie druhej verzie:

// hostiteľ / v2 / používatelia // hostiteľ / v2 / oprávnenie

Keď inovujeme typ média a rozšírime jazyk, prejdeme cez vyjednávanie o obsahu založené na tejto hlavičke. Rozhranie REST API by použilo vlastné typy médií MIME dodávateľa namiesto všeobecných typov médií, ako sú aplikácia / json. Namiesto URI ideme inovovať tieto typy médií.

Napríklad:

===> ZÍSKAŤ / users / 3 HTTP / 1.1 Accept: application / vnd.myname.v1 + json <=== HTTP / 1.1 200 OK Content-Type: application / vnd.myname.v1 + json {"user": {"name": "John Smith"}}

Ďalšie informácie a príklady týkajúce sa tejto témy si môžeme prečítať v tomto článku „Vlastné typy médií pre rozhrania Rest API“.

Tu je dôležité pochopiť, že klient nevytvára predpoklady o štruktúre odpovede nad rámec toho, čo je definované v type média.

To je dôvod, prečo generické typy médií nie sú ideálne. Títo neposkytujú dostatok sémantických informácií a prinútiť klienta, aby použil, vyžaduje ďalšie tipy na spracovanie skutočnej reprezentácie zdroja.

Výnimkou je použitie iného spôsobu jednoznačnej identifikácie sémantiky obsahu - napríklad schémy XML.

4. Výhody a nevýhody

Teraz, keď máme jasnú predstavu o tom, čo je súčasťou zmluvy medzi klientom a službou, ako aj prehľad na vysokej úrovni o možnostiach verzie API, poďme diskutovať o výhodách a nevýhodách každého prístupu.

Najprv, zavedenie identifikátorov verzií do URI vedie k veľmi veľkej stope URI. Je to spôsobené tým, že akákoľvek zlomová zmena v ktoromkoľvek zo zverejnených rozhraní API zavedie úplne nový strom reprezentácií pre celé rozhranie API. Z času na čas sa to stane bremenom údržby a problémom pre klienta - ktorý má teraz viac možností na výber.

Identifikátory verzií v URI ARE sú tiež veľmi nepružné. Neexistuje spôsob, ako jednoducho vyvinúť API jedného zdroja alebo malú podmnožinu celkového API.

Ako sme už spomínali, ide o prístup typu všetko alebo nič. Ak sa časť API presunie do novej verzie, musí s ňou prejsť aj celé API. To tiež robí z aktualizácie klientov z verzie 1 na verziu 2 veľkú záležitosť - čo vedie k pomalým aktualizáciám a oveľa dlhším obdobiam ukončenia platnosti starých verzií.

HTTP cache je tiež veľkým problémom, pokiaľ ide o správu verzií.

Z pohľadu proxy cache v strede má každý prístup výhody aj nevýhody. Ak má URI verziu, potom si vyrovnávacia pamäť bude musieť ponechať viac kópií každého zdroja - jednu pre každú verziu API. Tým sa zaťaží vyrovnávacia pamäť a zníži sa miera prístupov do pamäte cache, pretože rôzni klienti budú používať rôzne verzie.

Niektoré mechanizmy zneplatnenia vyrovnávacej pamäte už tiež nebudú fungovať. Ak je typom média ten, ktorý má verziu, potom musí klient aj služba podporovať hlavičku Vary HTTP, aby indikovala, že sa do pamäte cache ukladá viac verzií.

Z perspektíva cachovania klienta riešenie, ktoré poskytuje verziu typu média, však vyžaduje o niečo viac práce ako riešenie, kde identifikátory URI obsahujú identifikátor verzie. Je to preto, že je jednoducho jednoduchšie niečo uložiť do medzipamäte, keď jej kľúčom je adresa URL ako typ média.

Na záver tejto časti definujeme niektoré ciele (priamo z API Evolution):

• zachovať kompatibilné zmeny mimo mien
• vyhnúť sa novým hlavným verziám
• robí zmeny spätne kompatibilné
• myslite na doprednú kompatibilitu

5. Možné zmeny API

Ďalej zvážime typy zmien v rozhraní REST API - tieto sú uvedené tu:

• zmeny formátu reprezentácie
• zmeny zdrojov

5.1. Pridanie k predstaveniu zdroja

Dokumentácia formátu typu média by mala byť navrhnutá s ohľadom na kompatibilitu smerom dopredu. Klient by mal konkrétne ignorovať informácie, ktorým nerozumie (ktoré JSON sú lepšie ako XML).

Teraz, pridanie informácií do Zastúpenia zdroja nezruinuje existujúcich klientov, ak sú správne implementovaní.

Ak chcete pokračovať v predchádzajúcom príklade, pridajte znak čiastka v zastúpení používateľ nebude to zlomová zmena:

{"user": {"name": "John Smith", "amount": "300"}}

5.2. Odstránenie alebo zmena existujúceho zastúpenia

Odstránenie, premenovanie alebo všeobecná reštrukturalizácia informácií v dizajne existujúcich reprezentácií je pre klientov prelomovou zmenou. Je to tak preto, lebo už rozumejú starému formátu a spoliehajú sa na neho.

Tu prichádza na rad vyjednávanie o obsahu. Pre tieto zmeny môžeme pridať nový typ média MIME dodávateľa.

Pokračujme predchádzajúcim príkladom. Povedzme, že chceme prelomiť názov z používateľ do krstné meno a priezvisko:

===> ZÍSKAŤ / users / 3 HTTP / 1.1 Accept: application / vnd.myname.v2 + json <=== HTTP / 1.1 200 OK Content-Type: application / vnd.myname.v2 + json {"user": {"firstname": "John", "lastname": "Smith", "amount": "300"}}

Z tohto dôvodu to pre klienta predstavuje nekompatibilnú zmenu - ktorá bude musieť požiadať o nové zastúpenie a porozumieť novej sémantike. Priestor URI však zostane stabilný a nebude ovplyvnený.

5.3. Hlavné sémantické zmeny

Jedná sa o zmeny v zmysle zdrojov, vzťahov medzi nimi alebo toho, k čomu má mapa v backende. Tento druh zmien môže vyžadovať nový typ média alebo si môžu vyžadovať zverejnenie nového súrodeneckého zdroja vedľa starého a použitie odkazu na jeho uvedenie.

Aj keď to znie ako opakované použitie identifikátorov verzií v URI, je dôležité rozlišovať, že nový zdroj sa zverejňuje nezávisle od akýchkoľvek iných zdrojov v rozhraní API a nerozpozná celé API v koreni.

Rozhranie REST API by malo dodržiavať obmedzenie HATEOAS. Podľa toho by väčšinu URI mali OBJAVOVAŤ klienti, nie pevne zakódované. Zmena takého URI by sa nemala považovať za nekompatibilnú zmenu. Nový URI môže nahradiť ten starý a Klienti budú môcť znovu objaviť URI a stále fungovať.

Stojí za zmienku, že zatiaľ čo použitie identifikátorov verzií v URI je problematické zo všetkých týchto dôvodov, nie je to NEODDYCHLIVÉ akýmkoľvek spôsobom.

6. Záver

Tento článok sa pokúsil poskytnúť prehľad veľmi rozmanitého a zložitého problému vývoj služby REST. Diskutovali sme o dvoch bežných riešeniach, výhodách a nevýhodách každého z nich a spôsoboch uvažovania o týchto prístupoch v kontexte REST.

Na záver je potrebné spomenúť druhé riešenie - verzovanie typov médií pri skúmaní možných zmien v RESTful API.

Celú implementáciu tohto tutoriálu nájdete v projekte GitHub.

7. Ďalšie čítanie

Zvyčajne sú tieto zdroje na čítanie prepojené v celom článku, ale v takom prípade je dobrých príliš veľa:

• • Rozhrania REST API musia byť riadené hypertextom
  • Vývoj API
  • Prepojenie pre HTTP API
  • Stratégie kompatibility