streamalism.org

1. A probléma

A REST API fejlesztése nehéz probléma - amelyre számos lehetőség áll rendelkezésre. Ez a cikk ezek közül néhány lehetőséget tárgyal.

2. Mi szerepel a szerződésben?

Minden más előtt egy egyszerű kérdésre kell válaszolnunk: Mi a szerződés az API és a Ügyfél?

2.1. URI-k a szerződés része?

Először vegyük fontolóra a REST API URI felépítése - ez a szerződés része? Az ügyfeleknek könyvjelzőt, hardverkódot és általában az API URI-jára kell támaszkodniuk?

Ebben az esetben az Ügyfél és a REST szolgáltatás kölcsönhatását már nem maga a Szolgáltatás vezérli, hanem az, amit Roy Fielding hív sávon kívül információ:

A REST API-t előzetes ismeretek nélkül kell megadni a kezdeti URI-n (könyvjelzőn) és szabványosított adathordozó-típusokon túl, amelyek megfelelnek a tervezett közönségnek. A hiba itt azt jelenti, hogy a sávon kívüli információk kölcsönhatásba lépnek a hipertext helyett.

Olyan egyértelműen Az URI-k nem képezik a szerződés részét! Az ügyfélnek csak egyetlen URI-t kell tudnia - az API belépési pontját. Az összes többi URI-t az API fogyasztása során kell felfedezni.

2.2. Médiatípusok a szerződés része?

Mi a helyzet az erőforrások ábrázolásához használt médiatípusokkal - ezek az Ügyfél és a Szolgáltatás közötti szerződés részei?

Az API sikeres fogyasztása érdekében az Ügyfélnek előzetesen ismernie kell ezeket a médiatípusokat. Valójában e médiatípusok meghatározása képviseli a teljes szerződést.

Ezért itt kell leginkább a REST szolgáltatásra összpontosítania:

A REST API-nak csaknem minden leíró erőfeszítést az erőforrások ábrázolásához és az alkalmazás állapotának meghajtásához használt médiatípus (ok) meghatározásához, vagy a kiterjesztett relációnevek és / vagy a hiperszöveg által támogatott jelölések meghatározásához kell felhasználnia a meglévő szabványos médiatípusokhoz.

Így a A médiatípusok meghatározása a szerződés részét képezi és előzetes ismereteknek kell lenniük az API-t fogyasztó kliens számára. Itt jön be a szabványosítás.

Most már van egy jó ötletünk arról, hogy mi is a szerződés, térjünk át arra, hogyan lehet valóban megoldani a verziós problémát.

3. Magas szintű opciók

Beszéljünk most a REST API verziójának magas szintű megközelítéséről:

• URI verziószámítás - verziószám-mutatók segítségével verzióozza az URI helyet
• Médiatípus-verziószámítás - az erőforrás reprezentációjának verziója

Amikor bemutatjuk a verziót az URI térben, az erőforrások ábrázolása változhatatlannak tekinthető. Tehát amikor változtatásokat kell bevezetni az API-ban, új URI helyet kell létrehozni.

Tegyük fel például, hogy egy API a következő erőforrásokat teszi közzé - felhasználók és jogosultságok:

// host / v1 / users // host / v1 / privilégiumok

Most vegyük figyelembe, hogy a felhasználók Az API megköveteli egy második verzió bevezetését:

// host / v2 / users // host / v2 / privilégiumok

Amikor a médiatípust verzióvá alakítjuk és kibővítjük a nyelvet, ezen fejléc alapján megyünk át a tartalmi tárgyalásokon. A REST API egyedi szállítói MIME médiatípusokat használna az általános médiatípusok helyett, mint pl alkalmazás / json. Ezeket a médiatípusokat fogjuk az URI-k helyett használni.

Például:

===> GET / users / 3 HTTP / 1.1 Elfogadás: application / vnd.myname.v1 + json <=== HTTP / 1.1 200 OK Content-Type: application / vnd.myname.v1 + json {"user": {"name": "John Smith"}}

A témával kapcsolatban további információkat és példákat tekinthetünk meg ebben a „Custom Media Types for Rest APIs” cikkben.

Amit itt fontos megérteni, az az az ügyfél nem tételez fel feltételeket a válasz felépítésével kapcsolatban meghaladja a médiatípusban meghatározottakat.

Ezért az általános médiatípusok nem ideálisak. Ezek ne adjon elegendő szemantikai információt és kényszerítse az ügyfelet arra, hogy használjon további tippeket az erőforrás tényleges ábrázolásának feldolgozásához.

Ez alól kivételt jelent a tartalom szemantikájának egyedi azonosításának valamilyen más módja - például egy XML-séma.

4. Előnyök és hátrányok

Most, hogy világos koncepciónk van arról, hogy mi része az Ügyfél és a Szolgáltatás között létrejött szerződésnek, valamint magas szintű áttekintést adunk az API verziójának lehetőségeiről, beszéljük meg az egyes megközelítések előnyeit és hátrányait.

Első, verzióazonosítók bevezetése az URI-ba nagyon nagy URI-lábnyomhoz vezet. Ez annak a ténynek köszönhető, hogy a közzétett API-k bármelyikének megtörő változása egy teljesen új reprezentációs fát vezet be a teljes API-hoz. Idővel ez fenntartási terhet jelent, valamint problémát jelent az ügyfél számára - amelynek ma már több lehetősége van.

Az URI verzióazonosítói szintén nagyon rugalmatlanok. Nincs mód arra, hogy egyszerűen kifejlesszük egyetlen erőforrás API-ját, vagy a teljes API kis részhalmazát.

Mint korábban említettük, ez a mindent vagy semmit megközelítés. Ha az API egy része áttér az új verzióra, akkor az egész API-nak együtt kell mozognia. Ez szintén nagyvállalkozássá teszi az ügyfelek v1-ről v2-re történő frissítését - ami lassabb frissítésekhez és sokkal hosszabb lejárati időkhöz vezet a régi verziókhoz.

A HTTP gyorsítótárazás szintén komoly gondot jelent a verziókkal kapcsolatban.

A középen lévő proxy gyorsítótárak szempontjából minden megközelítésnek vannak előnyei és hátrányai. Ha az URI verzióval rendelkezik, akkor a gyorsítótárnak minden erőforrás több példányát meg kell őriznie - egyet az API minden változatához. Ez megterheli a gyorsítótárat és csökkenti a gyorsítótár találati arányát, mivel a különböző kliensek különböző verziókat fognak használni.

Emellett egyes gyorsítótár-érvénytelenítési mechanizmusok már nem fognak működni. Ha az adathordozó típusa verziószámú, akkor az Ügyfélnek és a Szolgáltatásnak egyaránt támogatnia kell a Vary HTTP fejlécet annak jelzésére, hogy több verzió van gyorsítótárban.

Tól az ügyfél gyorsítótárazásának perspektívája a médiatípust változatossá tevő megoldás azonban valamivel több munkát igényel, mint az, ahol az URI-k tartalmazzák a verzióazonosítót. Ennek az az oka, hogy egyszerűen könnyebb gyorsítótárazni valamit, ha a kulcs URL, mint egy médiatípus.

Fejezzük be ezt a részt néhány cél definiálásával (egyenesen az API Evolution alkalmazásból):

• tartsa a kompatibilis változásokat a neveken kívül
• kerülje az új főbb verziókat
• visszafelé kompatibilis változtatásokat végez
• gondoljon az előre-kompatibilitásra

5. Az API lehetséges változásai

Vizsgáljuk meg a REST API módosításainak típusait - ezeket itt mutatjuk be:

• az ábrázolás formátuma megváltozik
• erőforrás-változások

5.1. Hozzáadás az erőforrás ábrázolásához

A médiatípus formátumdokumentációját az előre történő kompatibilitás szem előtt tartásával kell megtervezni. Az ügyfélnek figyelmen kívül kell hagynia azokat az információkat, amelyeket nem ért (amelyeket a JSON jobban teljesít, mint az XML).

Most, információk hozzáadása az erőforrás ábrázolásához nem fogja megtörni a meglévő ügyfeleket, ha ezeket megfelelően hajtják végre.

Folytatva korábbi példánkat, a összeg ábrázolásában felhasználó nem lesz feltörő változás:

{"felhasználó": {"név": "John Smith", "összeg": "300"}}

5.2. Meglévő ábrázolás eltávolítása vagy módosítása

Az információk eltávolítása, átnevezése vagy általában átszervezése a meglévő reprezentációk kialakításában áttörő változás az ügyfelek számára. Ennek oka az, hogy már értik a régi formátumot és támaszkodnak rá.

Itt jön be a tartalmi tárgyalás. Ilyen változások esetén felvehetünk egy új szállítói MIME adathordozót.

Folytassuk az előző példával. Mondjuk, hogy meg akarjuk törni a név a felhasználó -ba keresztnév és vezetéknév:

===> GET / users / 3 HTTP / 1.1 Elfogadás: application / vnd.myname.v2 + json <=== HTTP / 1.1 200 OK Tartalom-típus: application / vnd.myname.v2 + json {"user": {"utónév": "John", "vezetéknév": "Smith", "összeg": "300"}}

Mint ilyen, ez összeférhetetlen változást jelent az Ügyfél számára - amelynek meg kell kérnie az új képviseletet és meg kell értenie az új szemantikát. Az URI tér azonban stabil marad, és ez nem lesz hatással.

5.3. Jelentősebb szemantikai változások

Ezek változások az erőforrások értelmében, a közöttük fennálló kapcsolatokban vagy abban, amit a háttérképen feltérképez. Ehhez a fajta változtatáshoz új médiatípusra lehet szükség, vagy új, testvér erőforrás közzétételére van szükség a régi mellett, és a linkelésre kell hivatkozni.

Bár ez úgy hangzik, mintha a verzióazonosítókat újból felhasználnánk az URI-ban, fontos különbséget tenni az új erőforrás között az API bármely más forrásától függetlenül jelenik meg és nem fogja elágazni a teljes API-t a gyökérnél.

A REST API-nak meg kell felelnie a HATEOAS korlátozásának. Eszerint az URI-k nagy részét az Ügyfeleknek kell FELFEDEZNI, nem pedig hardveresen kódolni. Egy ilyen URI megváltoztatása nem tekinthető összeférhetetlennek. Az új URI helyettesítheti a régit, és az ügyfelek újra felfedezhetik az URI-t, és továbbra is működhetnek.

Érdemes azonban megjegyezni, hogy bár a verzióazonosítók használata az URI-ban mindezen okokból problematikus, nem nyugtalan bármilyen módon.

6. Következtetés

Ez a cikk megpróbált áttekintést adni a a REST szolgáltatás fejlesztése. Megbeszéltük a két közös megoldást, az előnyöket és a hátrányokat, valamint a REST kontextusában ezeknek a megközelítéseknek az érvelését.

A cikk azzal zárul, hogy megalapozza a második megoldást - a médiatípusok verziószáma miközben megvizsgálja a RESTful API lehetséges változtatásait.

Az oktatóanyag teljes megvalósítása megtalálható a GitHub projektben.

7. További olvasmány

Ezek az olvasási források általában a cikk egészében összekapcsolódnak, de ebben az esetben egyszerűen túl sok jó van:

• • A REST API-knak hipertext-vezérelteknek kell lenniük
  • API Evolution
  • Linkelés egy HTTP API-hoz
  • Kompatibilitási stratégiák