Megosztás a következőn keresztül:

Ajánlott eljárások a RESTful webes API-tervezéséhez

A RESTful webes API-implementáció egy webes API, amely a reprezentációs állapotátvitel (REST) architektúra alapelveit alkalmazza az ügyfél és a szolgáltatás közötti állapot nélküli, lazán összekapcsolt felület eléréséhez. A RESTful web API támogatja a szabványos HTTP protokollt, hogy műveleteket hajtson végre az erőforrásokon, és olyan erőforrás-reprezentációkat adjon vissza, amelyek hipermédia-hivatkozásokat és HTTP-műveleti állapotkódokat tartalmaznak.

A RESTful webes API-nak az alábbi alapelveknek kell megfelelnie:

  • Platformfüggetlenség, ami azt jelenti, hogy az ügyfelek a belső megvalósítástól függetlenül meghívhatják a webes API-t. A platformfüggetlenség elérése érdekében a webes API a HTTP-t használja standard protokollként, egyértelmű dokumentációt biztosít, és támogatja a jól ismert adatcsere-formátumot, például a JSON-t vagy az XML-t.

  • Laza összekapcsolás, ami azt jelenti, hogy az ügyfél és a webszolgáltatás egymástól függetlenül fejlődhet. Az ügyfélnek nem kell ismernie a webszolgáltatás belső megvalósítását, és a webszolgáltatásnak nem kell ismernie az ügyfél belső implementációját. A RESTful webes API laza összekapcsolásához csak standard protokollokat használjon, és implementáljon egy olyan mechanizmust, amely lehetővé teszi az ügyfél és a webszolgáltatás számára, hogy megállapodjon az adatok cseréjének formátumáról.

Ez a cikk a RESTful webes API-k tervezésének ajánlott eljárásait ismerteti. Emellett a könnyen érthető, rugalmas és karbantartható webes API-k készítésének gyakori tervezési mintáit és szempontjait is ismerteti.

A RESTful webes API tervezési fogalmai

A RESTful webes API implementálásához ismernie kell az alábbi fogalmakat.

  • Egységes erőforrás-azonosító (URI): A REST API-k olyan erőforrások köré vannak tervezve, amelyek bármilyen objektum, adat vagy szolgáltatás, amelyhez az ügyfél hozzáférhet. Minden erőforrást egy URI jelöl, amely egyedileg azonosítja az erőforrást. Egy adott ügyfélrendelés URI-ja például a következő lehet:

    https://api.contoso.com/orders/1

  • Az erőforrás-ábrázolás azt határozza meg, hogy az URI által azonosított erőforrások hogyan vannak kódolva és átadva a HTTP protokollon keresztül egy adott formátumban, például XML vagy JSON formátumban. Az adott erőforrást lekérni kívánó ügyfeleknek az erőforrás URI-ját kell használniuk az API-nak küldött kérelemben. Az API az URI által jelzett adatok erőforrás-ábrázolását adja vissza. Az ügyfél például get kérést intézhet az URI-azonosítóhoz https://api.contoso.com/orders/1 a következő JSON-törzs fogadásához:

    {"orderId":1,"orderValue":99.9,"productId":1,"quantity":1}

  • Az egységes felület az, ahogyan a RESTful API-k laza kapcsolatot érnek el az ügyfél- és szolgáltatás-implementációk között. A HTTP-n alapuló REST API-k esetében az egységes felület magában foglalja a szabványos HTTP-parancsok használatát az olyan műveletek végrehajtásához, mint a GET, POST, PUT, PATCHés DELETE az erőforrások.

  • Állapot nélküli kérelemmodell: A RESTful API-k állapot nélküli kérelemmodellt használnak, ami azt jelenti, hogy a HTTP-kérések függetlenek, és bármilyen sorrendben előfordulhatnak. Ezért az átmeneti állapotadatok kérések közötti megőrzése nem lehetséges. Az információk tárolásának egyetlen helye maguk az erőforrások, és minden kérésnek atomi műveletnek kell lennie. Az állapot nélküli kérelmek modellje támogatja a nagy skálázhatóságot, mivel nem kell megőriznie az ügyfelek és az adott kiszolgálók közötti affinitást. Az állapot nélküli modell azonban korlátozhatja a méretezhetőséget is a webszolgáltatás háttérbeli tárolási méretezhetőségével kapcsolatos kihívások miatt. Az adattárak horizontális felskálázási stratégiáiról további információt az Adatparticionálás című témakörben talál.

  • Hypermedia-hivatkozások: A REST API-kat az egyes erőforrás-reprezentációkban található hipermédia-hivatkozások vezérelhetik. A következő kódblokk például egy megrendelés JSON-ábrázolását jeleníti meg. Hivatkozásokat tartalmaz a rendeléshez társított ügyfél lekéréséhez vagy frissítéséhez.

    {
  "orderID":3,
  "productID":2,
  "quantity":4,
  "orderValue":16.60,
  "links": [
    {"rel":"product","href":"https://api.contoso.com/customers/3", "action":"GET" },
    {"rel":"product","href":"https://api.contoso.com/customers/3", "action":"PUT" }
  ]
}

RESTful webes API-erőforrás URI-k definiálása

A RESTful webes API-k erőforrások köré vannak rendszerezve. Az API-tervezés erőforrások köré való rendszerezéséhez definiáljon olyan erőforrás-URI-kat, amelyek az üzleti entitásokhoz lesznek megfeleltetve. Ha lehetséges, alapozza az erőforrás URI-jait főnevekre (az erőforrásra) és ne az igékre (az erőforrás műveleteire).

Egy e-kereskedelmi rendszerben például az elsődleges üzleti entitások lehetnek ügyfelek és megrendelések. Rendelés létrehozásához az ügyfél egy HTTP POST-kérelemben elküldi a rendelési adatokat az erőforrás URI-jának. A kérelemRE adott HTTP-válasz jelzi, hogy a rendelés létrehozása sikeres-e.

A rendelési erőforrás létrehozásához használt URI a következőhöz hasonló lehet:

https://api.contoso.com/orders // Good

Ne használjon parancsokat az URI-kban a műveletek megjelenítéséhez. Például a következő URI nem ajánlott:

https://api.contoso.com/create-order // Avoid

Az entitások gyakran gyűjteményekbe, például ügyfelekbe vagy megrendelésekbe vannak csoportosítva. A gyűjtemény egy külön erőforrás a gyűjtemény elemeitől, ezért saját URI-val kell rendelkeznie. A következő URI például a megrendelések gyűjteményét jelentheti:

https://api.contoso.com/orders

Miután az ügyfél lekérte a gyűjteményt, get kérést tud küldeni az egyes elemek URI-jának. Ha például egy adott rendelésről szeretne információt kapni, az ügyfél HTTP GET kérést hajt végre az URI-n https://api.contoso.com/orders/1 , hogy a belső rendelési adatok erőforrás-ábrázolásaként megkapja a következő JSON-törzset:

{"orderId":1,"orderValue":99.9,"productId":1,"quantity":1}

Erőforrás URI elnevezési konvenciók

A RESTful webes API tervezésekor fontos, hogy az erőforrásokhoz a megfelelő elnevezési és kapcsolati konvenciókat használja:

  • Használjon főneveket az erőforrásnevekhez. Főnevek használatával jelölheti az erőforrásokat. Használjon például /orders/create-orderhelyett. A HTTP GET, POST, PUT, PATCH és DELETE metódusok már a verbális műveletet jelentik.

  • Többes számú főnévvel nevezze el a gyűjtemény URI-jait. Általában segít a gyűjteményekre hivatkozó URI-k többes számú főneveinek használatát. Ajánlott hierarchiába rendezni a gyűjtemények és elemek URI-jait. Például /customers az ügyfél gyűjteményének elérési útja, és /customers/5 az elérési út az ügyfélhez, akinek azonosítója 5. Ez a megközelítés segít intuitívan tartani a webes API-t. Emellett számos webes API-keretrendszer paraméteres URI-útvonalak alapján irányíthatja a kéréseket, így meghatározhatja az útvonal útvonalát /customers/{id}.

  • Vegye figyelembe a különböző típusú erőforrások közötti kapcsolatokat, és hogy hogyan teheti közzé ezeket a társításokat. Ez lehet például az /customers/5/orders 5. ügyfél összes megrendelése. A másik irányból is megközelítheti a kapcsolatot, ha a megrendelést az ügyfélhez kapcsoló társítást ábrázolja. Ebben a forgatókönyvben az URI lehet /orders/99/customer. A modell túl messzire történő kiterjesztése azonban nehézkessé válhat a implementáláshoz. Jobb módszer, ha hivatkozásokat tartalmaz a HTTP-válaszüzenet törzsébe, hogy az ügyfelek könnyen hozzáférhessenek a kapcsolódó erőforrásokhoz. Használja a Hypertextet az alkalmazásállapot motorjaként (HATEOAS) a kapcsolódó erőforrásokra való navigáció engedélyezéséhez , amely részletesebben ismerteti ezt a mechanizmust.

  • A kapcsolatok egyszerűek és rugalmasak maradnak. Összetettebb rendszerekben előfordulhat, hogy olyan URI-kat szeretne biztosítani, amelyek lehetővé teszik az ügyfél számára, hogy több kapcsolatszinten navigáljon, például /customers/1/orders/99/products. Ezt az összetettségi szintet azonban nehéz lehet fenntartani, és rugalmatlan, ha az erőforrások közötti kapcsolatok a jövőben megváltoznak. Ehelyett próbálja meg viszonylag egyszerűnek tartani az URI-kat. Miután egy alkalmazás hivatkozik egy erőforrásra, ezzel a hivatkozással megkeresheti az adott erőforráshoz kapcsolódó elemeket. Az előző lekérdezést lecserélheti az URI-ra /customers/1/orders az 1. ügyfél összes rendelésének megkereséséhez, majd a /orders/99/products megrendelésben szereplő termékek megkereséséhez.

    Jótanács

    Kerülje az olyan erőforrás-URI-k megkövetelését, amelyek összetettebbek, mint a gyűjtemény/elem/gyűjtemény.

  • Kerülje a nagy számú kis erőforrást. Minden webes kérés terhelést ró a webkiszolgálóra. Minél több kérés, annál nagyobb a terhelés. A nagy számú kis erőforrást elérhetővé tevő webes API-kat csevegő webes API-knak nevezzük. Próbálja elkerülni ezeket az API-kat, mert egy ügyfélalkalmazásnak több kérést kell küldenie az összes szükséges adat megkereséséhez. Ehelyett fontolja meg az adatok denormalizálását és a kapcsolódó információk nagyobb erőforrásokba való kombinálását, amelyek egyetlen kéréssel kérhetők le. Ezt a megközelítést azonban továbbra is ki kell egyensúlyoznia az ügyfél által nem igényelt adatok beolvasásának többletterhelésével. A nagy méretű objektumok lekérése növelheti a kérések késését, és nagyobb sávszélesség-költségekkel jár. További információ ezekről a teljesítmény antipatternökről: Chatty I/O és Extraneous Fetching.

  • Kerülje az adatbázisok belső struktúráját tükröző API-k létrehozását. A REST célja az üzleti entitások modellezése, valamint az alkalmazások által az adott entitásokon elvégezhető műveletek modellezése. Az ügyfélnek nem szabad a belső megvalósításnak kitéve lennie. Ha például az adatokat egy relációs adatbázisban tárolják, a webes API-nak nem kell minden táblát erőforrás-gyűjteményként elérhetővé tennie. Ez a megközelítés növeli a támadási felületet, és adatszivárgást okozhat. Ehelyett az adatbázis absztrakciójaként tekintsünk a webes API-ra. Szükség esetén vezessen be egy leképezési réteget az adatbázis és a webes API között. Ez a réteg biztosítja, hogy az ügyfélalkalmazások el legyenek különítve a mögöttes adatbázisséma változásaitól.

Jótanács

Előfordulhat, hogy a webes API által implementált összes műveletet nem lehet egy adott erőforráshoz hozzárendelni. Ezeket a nem forrásalapú forgatókönyveket olyan HTTP-kérésekkel kezelheti, amelyek függvényt hívnak meg, és az eredményeket HTTP-válaszüzenetként adják vissza.

Például egy olyan webes API, amely egyszerű kalkulátorműveleteket implementál, például a hozzáadást és kivonást, olyan URI-kat biztosít, amelyek álerőforrásként teszik elérhetővé ezeket a műveleteket, és a lekérdezési sztring használatával megadják a szükséges paramétereket. Az URI /add?operand1=99&operand2=1 get kérés egy válaszüzenetet ad vissza a 100 értéket tartalmazó törzstel.

Az URI-k ezen formáit azonban takarékosan kell használnia.

RESTful webes API-metódusok definiálása

A RESTful webes API-metódusok összhangban vannak a HTTP protokoll által definiált kérési módszerekkel és médiatípusokkal. Ez a szakasz a RESTful webes API-kban leggyakrabban használt kérési módszereket és médiatípusokat ismerteti.

HTTP-kérési metódusok

A HTTP-protokoll számos olyan kérésmetelyt határoz meg, amelyek jelzik az erőforráson végrehajtandó műveletet. A RESTful webes API-kban leggyakrabban használt módszerek a GET, a POST, a PUT, a PATCH és a DELETE. Minden metódus egy adott műveletnek felel meg. A RESTful webes API tervezésekor ezeket a metódusokat a protokolldefinícióval, az elérni kívánt erőforrással és a végrehajtott művelettel összhangban használja.

Fontos megjegyezni, hogy egy adott kérelemmetódus hatásának attól kell függenie, hogy az erőforrás gyűjtemény vagy egyedi elem-e. Az alábbi táblázat néhány konvenciót tartalmaz, amelyeket a legtöbb RESTful-implementáció használ.

Fontos

Az alábbi táblázat egy példa e-kereskedelmi customer entitást használ. A webes API-knak nem kell implementálniuk az összes kérési metódust. Az általa implementált módszerek az adott forgatókönyvtől függenek.

Erőforrás POSTA LEKÉR HELYEZ TÖRÖL
/Ügyfelek Új ügyfél létrehozása Az összes ügyfél lekérése Ügyfelek tömeges frissítése Az összes ügyfél eltávolítása
/customers/1 Hiba Az 1. ügyfél adatainak lekérése Az 1. ügyfél adatainak frissítése, ha létezik Ügyfél eltávolítása 1
/ügyfelek/1/rendelések Új rendelés létrehozása az 1. ügyfél számára Az 1. ügyfél összes rendelésének lekérése Az 1. ügyfél rendeléseinek tömeges frissítése Az 1. ügyfél összes rendelésének eltávolítása

GET-kérések

A GET-kérés lekéri az erőforrás ábrázolását a megadott URI-n. A válaszüzenet törzse tartalmazza a kért erőforrás részleteit.

A GET kérésnek a következő HTTP-állapotkódok egyikét kell visszaadnia:

HTTP-állapotkód Indok
200 (OK) A metódus sikeresen visszaadta az erőforrást.
204 (Nincs tartalom) A válasz törzse nem tartalmaz tartalmat, például ha egy keresési kérés nem ad vissza egyezést a HTTP-válaszban.
404 (nem található) A kért erőforrás nem található.

POST-kérelmek

A POST-kérésnek létre kell hoznia egy erőforrást. A kiszolgáló hozzárendel egy URI-t az új erőforráshoz, és visszaadja az URI-t az ügyfélnek.

Fontos

POST-kérelmek esetén az ügyfélnek nem szabad saját URI-t létrehoznia. Az ügyfélnek el kell küldenie a kérést a gyűjtemény URI-jának, és a kiszolgálónak URI-t kell hozzárendelnie az új erőforráshoz. Ha egy ügyfél megkísérli létrehozni a saját URI-ját, és post kérést küld egy adott URI-nak, a kiszolgáló a 400-ás HTTP-állapotkódot (BAD REQUEST) adja vissza, amely jelzi, hogy a metódus nem támogatott.

A RESTful modellben a POST-kérelmek egy új erőforrás hozzáadására szolgálnak az URI által azonosított gyűjteményhez. A POST-kérések azonban arra is használhatók, hogy adatokat küldjenek feldolgozásra egy meglévő erőforrásnak, új erőforrás létrehozása nélkül.

A POST-kérésnek a következő HTTP-állapotkódok egyikét kell visszaadnia:

HTTP-állapotkód Indok
200 (OK) A metódus némi feldolgozást végzett, de nem hoz létre új erőforrást. A művelet eredménye bele is kerülhet a válasz törzsbe.
201 (Létrehozva) Az erőforrás létrehozása sikeresen megtörtént. Az új erőforrás URI-ja a válasz Hely fejlécében található. A válasz törzse az erőforrás ábrázolását tartalmazza.
204 (Nincs tartalom) A válasz törzse nem tartalmaz tartalmat.
400 (Hibás kérés) Az ügyfél érvénytelen adatokat helyezett el a kérelemben. A válasz törzse további információkat tartalmazhat a hibáról, vagy egy URI-ra mutató hivatkozást, amely további részleteket tartalmaz.
405 (a metódus nem engedélyezett) Az ügyfél olyan URI-nak próbált POST-kérelmet küldeni, amely nem támogatja a POST-kérelmeket.

PUT-kérés

A PUT-kérésnek frissítenie kell egy meglévő erőforrást, ha létezik, vagy bizonyos esetekben új erőforrást kell létrehoznia, ha nem létezik. PUT-kérés kérése:

  1. Az ügyfél megadja az erőforrás URI-ját, és tartalmaz egy kérelemtörzset, amely az erőforrás teljes megjelenítését tartalmazza.
  2. Az ügyfél intézi a kérést.
  3. Ha már létezik ilyen URI-t tartalmazó erőforrás, a program lecseréli. Ellenkező esetben egy új erőforrás jön létre, ha az útvonal támogatja azt.

A PUT metódusok a gyűjtemények helyett az egyes elemeket tartalmazó erőforrásokra, például egy adott ügyfélre lesznek alkalmazva. Előfordulhat, hogy a kiszolgáló támogatja a frissítéseket, de a PUT használatával történő létrehozást nem. Attól függ, hogy támogatja-e a PUT használatával történő létrehozást, attól függ, hogy az ügyfél képes-e értelmesen és megbízhatóan hozzárendelni egy URI-t egy erőforráshoz annak megléte előtt. Ha nem tudja, akkor a POST használatával hozzon létre erőforrásokat, és rendelje hozzá a kiszolgálóhoz az URI-t. Ezután a PUT vagy a PATCH használatával frissítse az URI-t.

Fontos

A PUT-kérelmeknek idempotensnek kell lenniük, ami azt jelenti, hogy ugyanazon kérelem többszöri elküldése mindig ugyanazt az erőforrást módosítja ugyanazokkal az értékekkel. Ha egy ügyfél újra elküld egy PUT-kérést, az eredményeknek változatlannak kell maradniuk. Ezzel szemben a POST és a PATCH kérések nem garantáltan idempotensek.

A PUT-kérésnek a következő HTTP-állapotkódok egyikét kell visszaadnia:

HTTP-állapotkód Indok
200 (OK) Az erőforrás frissítése sikeresen megtörtént.
201 (Létrehozva) Az erőforrás létrehozása sikeresen megtörtént. A válasz törzse az erőforrás ábrázolását is tartalmazhatja.
204 (Nincs tartalom) Az erőforrás frissítése sikeresen megtörtént, de a válasz törzse nem tartalmaz tartalmat.
409 (Ütközés) A kérés nem hajtható végre, mert ütközik az erőforrás aktuális állapotával.

Jótanács

Fontolja meg tömeges HTTP PUT-műveletek implementálását, amelyek a gyűjtemény több erőforrásának frissítését kötegelhetik. A PUT-kérésnek meg kell adnia a gyűjtemény URI-ját. A kérelem törzsének meg kell adnia a módosítani kívánt erőforrások részleteit. Ez a megközelítés segíthet csökkenteni a csevegést és javítani a teljesítményt.

PATCH kérelmek

A PATCH-kérések egy meglévő erőforrás részleges frissítését hajtják végre. Az ügyfél megadja az erőforrás URI-címét. A kérelem törzse meghatározza az erőforrásra alkalmazandó módosítások készletét. Ez a módszer hatékonyabb lehet, mint a PUT-kérések használata, mivel az ügyfél csak a módosításokat küldi el, és nem az erőforrás teljes megjelenítését. A PATCH új erőforrást is létrehozhat, ha egy üres vagy null értékű erőforrás frissítési készletét adja meg, ha a kiszolgáló támogatja ezt a műveletet.

PATCH-kéréssel az ügyfél frissítéseket küld egy meglévő erőforrásnak javításdokumentum formájában. A kiszolgáló feldolgozza a javítás dokumentumát a frissítés végrehajtásához. A javítási dokumentum csak egy módosításkészletet határoz meg, amelyeket a teljes erőforrás leírása helyett alkalmazni kell. A PATCH metódus ( RFC 5789) specifikációja nem határoz meg egy adott formátumot a javításdokumentumokhoz. A formátumot a kérelemben szereplő médiatípusból kell következtetni.

A JSON a webes API-k egyik leggyakoribb adatformátuma. A két fő JSON-alapú javításformátum a JSON-javítás és a JSON-egyesítési javítás.

A JSON-egyesítési javítás egyszerűbb, mint a JSON-javítás. A javítási dokumentum struktúrája megegyezik az eredeti JSON-erőforráséval, de csak a módosítandó vagy hozzáadandó mezők részhalmazát tartalmazza. Emellett egy mező törölhető a javítási dokumentumban megadott mezőérték megadásával null . Ez a specifikáció azt jelenti, hogy az egyesítési javítás nem megfelelő, ha az eredeti erőforrás explicit null értékekkel rendelkezhet.

Tegyük fel például, hogy az eredeti erőforrás a következő JSON-ábrázolású:

{
    "name":"gizmo",
    "category":"widgets",
    "color":"blue",
    "price":10
}

Íme egy lehetséges JSON-egyesítési javítás ehhez az erőforráshoz:

{
    "price":12,
    "color":null,
    "size":"small"
}

Ez az egyesítési javítás tájékoztatja a kiszolgálót a frissítésről price, a törlésről colorés a hozzáadásról size. Az name és category értékek nincsenek módosítva. További információ a JSON-egyesítési javításról: RFC 7396. A JSON-egyesítési javítás médiatípusa: application/merge-patch+json.

Az "egyesítési javítás" nem alkalmas, ha az eredeti erőforrás explicit null értékeket tartalmazhat, mivel ezeknek különleges jelentése lehet a null jelölés miatt a javításdokumentumban. A javítási dokumentum azt a sorrendet sem határozza meg, hogy a kiszolgáló alkalmazza a frissítéseket. Az adatoktól és a tartománytól függ, hogy ez a sorrend számít-e. Az RFC 6902-ben definiált JSON-javítás rugalmasabb, mivel a módosításokat műveletek sorozataként határozza meg, beleértve a hozzáadást, az eltávolítást, a csere, a másolást és a tesztelést az értékek érvényesítéséhez. A JSON-javítás médiatípusa application/json-patch+json.

A PATCH-kérésnek a következő HTTP-állapotkódok egyikét kell visszaadnia:

HTTP-állapotkód Indok
200 (OK) Az erőforrás frissítése sikeresen megtörtént.
400 (Hibás kérés) Hibásan formázott javítási dokumentum.
409 (Ütközés) A javítási dokumentum érvényes, de a módosítások nem alkalmazhatók az erőforrásra az aktuális állapotában.
415 (Nem támogatott médiatípus) A javítás dokumentumformátuma nem támogatott.

DELETE-kérések

A DELETE-kérés eltávolítja az erőforrást a megadott URI-n. A DELETE kérésnek a következő HTTP-állapotkódok egyikét kell visszaadnia:

HTTP-állapotkód Indok
204 (NINCS TARTALOM) Az erőforrást sikeresen törölték. A folyamat kezelése sikeresen megtörtént, és a válasz törzse nem tartalmaz további információt.
404 (NEM TALÁLHATÓ) Az erőforrás nem létezik.

Erőforrás MIME-típusai

Az erőforrás-ábrázolás az URI által azonosított erőforrások kódolása és átvitele a HTTP protokollon keresztül, egy adott formátumban, például XML vagy JSON formátumban. Az adott erőforrást lekérni kívánó ügyfeleknek az URI-t kell használniuk az API-nak küldött kérésben. Az API az URI által jelzett adatok erőforrás-ábrázolásával válaszol.

A HTTP-protokollban az erőforrás-ábrázolás formátumai médiatípusok, más néven MIME-típusok használatával vannak megadva. Nembináris adatok esetén a legtöbb webes API támogatja a JSON-t (médiatípus = application/json) és esetleg XML-t (médiatípus = application/xml).

A kérelem vagy válasz Tartalomtípus fejléce megadja az erőforrás-ábrázolás formátumát. Az alábbi példa egy JSON-adatokat tartalmazó POST-kérést mutat be:

POST https://api.contoso.com/orders
Content-Type: application/json; charset=utf-8
Content-Length: 57

{"Id":1,"Name":"Gizmo","Category":"Widgets","Price":1.99}

Ha a kiszolgáló nem támogatja a médiatípust, akkor a 415-ös HTTP-állapotkódot kell visszaadnia (nem támogatott médiatípus).

Az ügyfélkérések tartalmazhatnak egy Accept fejlécet, amely tartalmazza az ügyfél által a kiszolgálótól a válaszüzenetben elfogadott médiatípusok listáját. Például:

GET https://api.contoso.com/orders/2
Accept: application/json, application/xml

Ha a kiszolgáló nem tud egyezni a felsorolt médiatípusok egyikével sem, akkor a 406-os (nem elfogadható) HTTP-állapotkódot kell visszaadnia.

Aszinkron metódusok implementálása

Előfordulhat, hogy a POST, a PUT, a PATCH vagy a DELETE metódus feldolgozása időt vesz igénybe. Ha megvárja a befejezést, az elfogadhatatlan késést okozhat, mielőtt válaszát elküldi az ügyfélnek. Ebben a forgatókönyvben fontolja meg a módszer aszinkronvá tételét. Az aszinkron metódusnak a 202-ben (elfogadva) megadott HTTP-állapotkódot kell visszaadnia, amely jelzi, hogy a kérelem feldolgozásra elfogadva lett, de nem teljes.

Tegye elérhetővé az aszinkron kérés állapotát visszaadó végpontot, hogy az ügyfél az állapotvégpont lekérdezésével figyelhesse az állapotot. Adja meg az állapotvégpont URI-ját a 202-válasz Hely fejlécében. Például:

HTTP/1.1 202 Accepted
Location: /api/status/12345

Ha az ügyfél GET kérést küld erre a végpontra, a válasznak tartalmaznia kell a kérés aktuális állapotát. Opcionálisan a művelet befejezésének becsült idejét vagy a művelet megszakítására mutató hivatkozást is tartalmazhat.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status":"In progress",
    "link": { "rel":"cancel", "method":"delete", "href":"/api/status/12345" }
}

Ha az aszinkron művelet új erőforrást hoz létre, az állapotvégpontnak a művelet befejezése után a 303-nak (lásd az egyéb) állapotkódot kell visszaadnia. A 303-ra adott válaszban adjon meg egy Hely fejlécet, amely megadja az új erőforrás URI-ját:

HTTP/1.1 303 See Other
Location: /api/orders/12345

További információ: Aszinkron támogatás biztosítása hosszú ideig futó kérelmekhez és aszinkron Request-Reply mintához.

Adatszámozás és -szűrés implementálása

Az adatlekérés optimalizálásához és a hasznos adatok méretének csökkentéséhez hajtsa végre az adatszámozást és a lekérdezésalapú szűrést az API-tervezésben. Ezek a technikák lehetővé teszik az ügyfelek számára, hogy csak a szükséges adathalmazt kérik le, ami javíthatja a teljesítményt és csökkentheti a sávszélesség-használatot.

  • A lapozás a nagy adathalmazokat kisebb, kezelhető adattömbökre osztja. Lekérdezési paramétereket használjon, például limit adja meg a visszaadni kívánt elemek számát, és offset adja meg a kiindulási pontot. Győződjön meg arról, hogy a megfelelő alapértelmezett értékeket limitoffsetis megadja, például limit=25 és offset=0. Például:

    GET /orders?limit=25&offset=50

    • limit: A visszaadandó elemek maximális számát adja meg.

      Jótanács

      A szolgáltatásmegtagadásos támadások megelőzése érdekében érdemes lehet felső határt szabni a visszaadott elemek számának. Ha például a szolgáltatás beállítja a max-limit=25, és egy ügyfél kér egy limit=1000, a szolgáltatás az API dokumentációjától függően 25 elemet vagy egy HTTP-BAD-REQUEST hibát tud visszaadni.

    • offset: Az adatok kezdő indexét adja meg.

  • A szűrés lehetővé teszi az ügyfelek számára az adathalmaz finomítását feltételek alkalmazásával. Az API lehetővé teszi, hogy az ügyfél átadja a szűrőt az URI lekérdezési sztringjében:

    GET /orders?minCost=100&status=shipped
    • minCost: Szűri a 100-as minimális költségű rendeléseket.
    • status: Szűri az adott állapotú rendeléseket.

Vegye figyelembe a következő ajánlott eljárásokat:

  • A rendezés lehetővé teszi az ügyfelek számára az adatok rendezését egy olyan paraméterrel, mint a sortsort=price.

    Fontos

    A rendezési módszer negatív hatással lehet a gyorsítótárazásra, mivel a lekérdezési sztringparaméterek az erőforrás-azonosító részét képezik, amelyet számos gyorsítótár-implementáció használ a gyorsítótárazott adatok kulcsaként.

  • Az ügyfél által definiált előrejelzések mezőválasztása lehetővé teszi, hogy az ügyfelek csak a szükséges mezőket adják meg egy olyan paraméterrel, mint a fieldsfields=id,name. Használhat például olyan lekérdezési sztringparamétert, amely elfogadja a mezők vesszővel tagolt listáját, például /orders?fields=ProductID,Quantity.

Az API-nak ellenőriznie kell a kért mezőket, hogy az ügyfél hozzáférhessen hozzájuk, és ne tegye közzé azOKAT a mezőket, amelyek általában nem érhetők el az API-val.

Részleges válaszok támogatása

Egyes erőforrások nagy bináris mezőket, például fájlokat vagy képeket tartalmaznak. A megbízhatatlan és időszakos kapcsolatok okozta problémák megoldása és a válaszidő javítása érdekében fontolja meg a nagy bináris erőforrások részleges lekérésének támogatását.

A részleges válaszok támogatásához a webes API-nak támogatnia kell a Accept-Ranges fejlécet a nagy erőforrások get kéréseihez. Ez a fejléc azt jelzi, hogy a GET művelet támogatja a részleges kéréseket. Az ügyfélalkalmazás olyan GET kéréseket küldhet, amelyek egy erőforrás egy részhalmazát adják vissza bájttartományként megadva.

Fontolja meg ezen erőforrások HTTP HEAD-kéréseinek implementálását is. A HEAD-kérések hasonlóak a GET-kérésekhez, azzal a különbséggel, hogy csak az erőforrást leíró HTTP-fejléceket adja vissza üres üzenettörzsgel. Az ügyfélalkalmazások egy HEAD-kérést adhatnak ki, amely meghatározza, hogy részleges GET-kérések használatával kell-e lekérni egy erőforrást. Például:

HEAD https://api.contoso.com/products/10?fields=productImage

Íme egy példa válaszüzenet:

HTTP/1.1 200 OK

Accept-Ranges: bytes
Content-Type: image/jpeg
Content-Length: 4580

A Content-Length fejléc az erőforrás teljes méretét adja meg, a Accept-Ranges fejléc pedig azt jelzi, hogy a megfelelő GET művelet támogatja a részleges eredményeket. Az ügyfélalkalmazás ezeket az információkat használhatja a rendszerkép kisebb adattömbökben való lekéréséhez. Az első kérés az első 2500 bájtot kéri le a Tartomány fejléc használatával:

GET https://api.contoso.com/products/10?fields=productImage
Range: bytes=0-2499

A válaszüzenet azt jelzi, hogy ez a válasz részleges a 206-os HTTP-állapotkód visszaadásával. A Content-Length fejléc az üzenet törzsében visszaadott bájtok tényleges számát adja meg, nem pedig az erőforrás méretét. A Content-Range fejléc az erőforrás melyik részét adja vissza (0–2499 bájt a 4580-ból):

HTTP/1.1 206 Partial Content

Accept-Ranges: bytes
Content-Type: image/jpeg
Content-Length: 2500
Content-Range: bytes 0-2499/4580

[...]

Az ügyfélalkalmazás későbbi kérései lekérhetik az erőforrás fennmaradó részét.

HATEOAS implementálása

A REST használatának egyik elsődleges oka az, hogy az URI-séma előzetes ismerete nélkül navigálhat a teljes erőforráskészletben. Minden HTTP GET-kérésnek vissza kell adnia a közvetlenül a kért objektumhoz kapcsolódó erőforrások megkereséséhez szükséges információkat a válaszban található hivatkozásokon keresztül. A kérésnek olyan információkat is meg kell adni, amelyek az egyes erőforrásokon elérhető műveleteket ismertetik. Ezt az alapelvet HATEOAS-nak vagy Hypertext-nek nevezzük, mint az alkalmazásállapot motorját. A rendszer gyakorlatilag véges állapotú gép, és az egyes kérések válasza tartalmazza azokat az információkat, amely az egyik állapotból a másikba való áthelyezéshez szükséges. Nincs szükség más információra.

Megjegyzés

Nincsenek általános célú szabványok, amelyek meghatározzák a HATEOAS-elv modellezését. Az ebben a szakaszban szereplő példák egy lehetséges, védett megoldást mutatnak be.

Egy megrendelés és egy ügyfél közötti kapcsolat kezeléséhez például a megrendelések megjelenítése tartalmazhat olyan hivatkozásokat, amelyek azonosítják a rendelés ügyfélének elérhető műveleteit. A következő kódblokk egy lehetséges ábrázolás:

{
  "orderID":3,
  "productID":2,
  "quantity":4,
  "orderValue":16.60,
  "links":[
    {
      "rel":"customer",
      "href":"https://api.contoso.com/customers/3",
      "action":"GET",
      "types":["text/xml","application/json"]
    },
    {
      "rel":"customer",
      "href":"https://api.contoso.com/customers/3",
      "action":"PUT",
      "types":["application/x-www-form-urlencoded"]
    },
    {
      "rel":"customer",
      "href":"https://api.contoso.com/customers/3",
      "action":"DELETE",
      "types":[]
    },
    {
      "rel":"self",
      "href":"https://api.contoso.com/orders/3",
      "action":"GET",
      "types":["text/xml","application/json"]
    },
    {
      "rel":"self",
      "href":"https://api.contoso.com/orders/3",
      "action":"PUT",
      "types":["application/x-www-form-urlencoded"]
    },
    {
      "rel":"self",
      "href":"https://api.contoso.com/orders/3",
      "action":"DELETE",
      "types":[]
    }]
}

Ebben a példában a links tömb hivatkozásokat tartalmaz. Minden hivatkozás egy kapcsolódó entitáson végzett műveletet jelöl. Az egyes hivatkozások adatai közé tartozik a kapcsolat ("ügyfél"), az URI (https://api.contoso.com/customers/3), a HTTP metódus és a támogatott MIME-típusok. Az ügyfélalkalmazásnak szüksége van ezekre az információkra a művelet meghívásához.

A links tömb önhivatkozási információkat is tartalmaz a lekért erőforrásról. Ezek a hivatkozások a kapcsolat self-el rendelkeznek.

A visszaadott hivatkozások az erőforrás állapotától függően változhatnak. Ezt a forgatókönyvet az a gondolat írja le, hogy a hiperszöveg az alkalmazásállapot motorja .

Verziókezelés implementálása

A webes API-k nem maradnak statikusak. Az üzleti követelmények változásával új erőforrásgyűjtemények jelennek meg. Az új erőforrások hozzáadásakor az erőforrások közötti kapcsolatok megváltozhatnak, és az erőforrásokban lévő adatok struktúrája módosítható. A webes API frissítése új vagy eltérő követelmények kezelésére egyszerű folyamat, de figyelembe kell vennie, hogy az ilyen módosítások milyen hatással vannak a webes API-t használó ügyfélalkalmazásokra. A webes API-t tervező és megvalósító fejlesztő teljes körűen felügyeli ezt az API-t, de a partnerszervezetek által létrehozott ügyfélalkalmazások nem rendelkeznek ugyanolyan szintű vezérléssel. Fontos, hogy továbbra is támogassa a meglévő ügyfélalkalmazásokat, miközben az új ügyfélalkalmazások új funkciókat és erőforrásokat használhatnak.

A verziószámozást megvalósító webes API-k jelezhetik az általa kínált szolgáltatásokat és erőforrásokat, az ügyfélalkalmazás pedig elküldheti azokat a kéréseket, amelyek egy szolgáltatás vagy erőforrás egy adott verziójára irányulnak. A következő szakaszok számos különböző megközelítést ismertetnek, amelyek mindegyike saját előnyökkel és kompromisszumokkal rendelkezik.

Nincs verziószámozás

Ez a módszer a legegyszerűbb, és néhány belső API-hoz használható. A jelentős változások új erőforrásokként vagy új hivatkozásokként jelenhetnek meg. Előfordulhat, hogy a tartalom meglévő erőforrásokhoz való hozzáadása nem jelent kompatibilitástörő változást, mert azok az ügyfélalkalmazások, amelyek nem várják, hogy ezt a tartalmat lássák, figyelmen kívül hagyják.

Az URI-nak https://api.contoso.com/customers/3 küldött kérésnek például egyetlen ügyfél adatait kell visszaadnia, amely tartalmazza az idügyfélalkalmazás által várt , nameés address mezőket:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","address":"1 Microsoft Way Redmond WA 98053"}

Megjegyzés

Az egyszerűség kedvéért az ebben a szakaszban látható példaválaszok nem tartalmaznak HATEOAS-hivatkozásokat.

Ha a DateCreated mező hozzá van adva az ügyfélerőforrás sémáihoz, a válasz a következőképpen néz ki:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","dateCreated":"2025-03-22T12:11:38.0376089Z","address":"1 Microsoft Way Redmond WA 98053"}

A meglévő ügyfélalkalmazások továbbra is megfelelően működnek, ha figyelmen kívül hagyhatják a nem felismert mezőket. Eközben az új ügyfélalkalmazásokat úgy lehet megtervezni, hogy kezelni tudják ezt az új mezőt. Azonban az erőforrások séma drasztikusabb módosításai, beleértve a mezők eltávolítását vagy átnevezését, is bekövetkezhetnek. Vagy az erőforrások közötti kapcsolatok megváltozhatnak. Ezek a frissítések olyan kompatibilitástörő változásokat okozhatnak, amelyek megakadályozzák a meglévő ügyfélalkalmazások megfelelő működését. Ezekben a forgatókönyvekben vegye figyelembe az alábbi módszerek egyikét:

URI-verziószámozás

Minden alkalommal, amikor módosítja a webes API-t, vagy módosítja az erőforrások sémáját, minden erőforráshoz hozzáad egy verziószámot az URI-hoz. A korábban meglévő URI-knak továbbra is normálisan kell működniük az eredeti sémájuknak megfelelő erőforrások visszaadásával.

Az előző példában szereplő mező például address almezőkké lesz strukturálva, amelyek a cím egyes összetevőit tartalmazzák, például streetAddress: , city, stateés zipCode. Az erőforrás ezen verziója egy verziószámot tartalmazó URI-val érhető el, például https://api.contoso.com/v2/customers/3:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","dateCreated":"2025-03-22T12:11:38.0376089Z","address":{"streetAddress":"1 Microsoft Way","city":"Redmond","state":"WA","zipCode":98053}}

Ez a verziószámozási mechanizmus egyszerű, de a kiszolgálótól függ, hogy a kérést a megfelelő végpontra irányíthassa. Azonban ahogy a webes API több iteráción keresztül fejlődik, nehézkessé válhat, mivel a kiszolgálónak számos különböző verziót kell támogatnia. A purist szempontjából az ügyfélalkalmazások minden esetben ugyanazokat az adatokat kérik le (3. ügyfél), így az URI-nak nem szabad eltérnie a verziótól függően. Ez a séma bonyolítja a HATEOAS megvalósítását is, mivel minden hivatkozásnak tartalmaznia kell a verziószámot az URI-kban.

Lekérdezési karakterlánc verziószámozása

Ahelyett, hogy több URI-t adna meg, megadhatja az erőforrás verzióját egy, a HTTP-kérelemhez hozzáfűzött lekérdezési sztringen belüli paraméterrel, például https://api.contoso.com/customers/3?version=2. Ha a régebbi ügyfélalkalmazások kihagyják azt, a verzióparaméternek alapértelmezés szerint egy értelmes értéknek kell lennie( például 1).

Ennek a megközelítésnek az a szemantikai előnye, hogy ugyanazt az erőforrást mindig ugyanabból az URI-ból kéri le a rendszer. Ez a módszer azonban attól a kódtól függ, amely a lekérdezési sztring elemzésére és a megfelelő HTTP-válasz visszaküldésére irányuló kérést kezeli. Ez a megközelítés az URI verziószámozási mechanizmusával megegyező módon bonyolítja a HATEOAS megvalósítását is.

Megjegyzés

Egyes régebbi webböngészők és webes proxyk nem gyorsítótárazják a lekérdezési sztringet tartalmazó kérések válaszait az URI-ban. A nem gyorsítótárazott válaszok csökkenthetik a webes API-t használó és egy régebbi böngészőből futtatott webalkalmazások teljesítményét.

Fejléc verziószámozása

A verziószám lekérdezési sztringparaméterként való hozzáfűzése helyett implementálhat egy egyéni fejlécet, amely az erőforrás verzióját jelzi. Ehhez a megközelítéshez az ügyfélalkalmazásnak hozzá kell adnia a megfelelő fejlécet minden kéréshez. Az ügyfélkérést kezelő kód azonban használhat alapértelmezett értéket, például az 1. verziót, ha a verziófejléc nincs megadva.

Az alábbi példák egy Custom-Header nevű egyéni fejlécet használnak. A fejléc értéke a webes API verzióját jelzi.

1. verzió:

GET https://api.contoso.com/customers/3
Custom-Header: api-version=1

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","address":"1 Microsoft Way Redmond WA 98053"}

2. verzió:

GET https://api.contoso.com/customers/3
Custom-Header: api-version=2

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","dateCreated":"2025-03-22T12:11:38.0376089Z","address":{"streetAddress":"1 Microsoft Way","city":"Redmond","state":"WA","zipCode":98053}}

Az URI-verziószámozáshoz és a lekérdezési sztring verziószámozásához hasonlóan a HATEOAS implementálásához minden hivatkozásban meg kell adnia a megfelelő egyéni fejlécet.

Médiatípus verziószámozása

Amikor egy ügyfélalkalmazás HTTP GET kérést küld egy webkiszolgálónak, egy Elfogadás fejlécet kell használnia a kezelni kívánt tartalom formátumának megadásához. Az Accept fejléc célja általában az, hogy lehetővé tegye az ügyfélalkalmazás számára annak megadását, hogy a válasz törzsének XML, JSON vagy más, az ügyfél által elemezhető általános formátumnak kell-e lennie. Megadhat azonban olyan egyéni médiatípusokat, amelyek olyan információkat tartalmaznak, amelyekkel az ügyfélalkalmazás jelezheti az erőforrás várt verzióját.

Az alábbi példa egy kérelmet mutat be, amely egy Elfogadás fejlécet ad meg az értékkel application/vnd.contoso.v1+json. Az vnd.contoso.v1 elem azt jelzi a webkiszolgálónak, hogy az erőforrás 1. verzióját kell visszaadnia. Az json elem meghatározza, hogy a válasz törzsének formátuma JSON legyen:

GET https://api.contoso.com/customers/3
Accept: application/vnd.contoso.v1+json

A kérést kezelő kód felelős az Elfogadás fejléc feldolgozásáért és a lehető legnagyobb mértékű tiszteletben helyezéséért. Az ügyfélalkalmazás több formátumot is megadhat az Elfogadás fejlécben, így a webkiszolgáló kiválaszthatja a válasz törzsének legmegfelelőbb formátumot. A webkiszolgáló a Content-Type fejléc használatával megerősíti a válasz törzsében lévő adatok formátumát:

HTTP/1.1 200 OK
Content-Type: application/vnd.contoso.v1+json; charset=utf-8

{"id":3,"name":"Fabrikam, Inc.","address":"1 Microsoft Way Redmond WA 98053"}

Ha az Elfogadás fejléc nem ad meg ismert médiatípusokat, a webkiszolgáló http 406-os (nem elfogadható) válaszüzenetet hozhat létre, vagy egy alapértelmezett médiatípusú üzenetet adhat vissza.

Ez a verziószámozási mechanizmus egyszerű és jól használható a HATEOAS esetében, amely a kapcsolódó adatok MIME-típusát is belefoglalhatja az erőforrás-hivatkozásokba.

Megjegyzés

Amikor verziószámozási stratégiát választunk, fontolóra kell venni a következményeket, különösen a webkiszolgáló gyorsítótárazásával kapcsolatban. Az URI-verziószámozás és a lekérdezési sztring verziószámozási sémái gyorsítótárbarátak, mivel minden alkalommal ugyanaz az URI- vagy lekérdezési sztring-kombináció ugyanarra az adatra hivatkozik.

A fejléc verziószámozási és médiatípus-verziószámozási mechanizmusai általában több logikát igényelnek az egyéni fejléc vagy az Elfogadás fejléc értékeinek vizsgálatához. Nagy méretű környezetben a webes API különböző verzióit használó ügyfelek jelentős mennyiségű duplikált adatot eredményezhetnek a kiszolgálóoldali gyorsítótárban. Ez a probléma akkor fordulhat elő, ha egy ügyfélalkalmazás gyorsítótárazást megvalósító proxyn keresztül kommunikál egy webkiszolgálóval, és csak akkor továbbít egy kérést a webkiszolgálónak, ha jelenleg nem tartalmazza a kért adatok másolatát a gyorsítótárában.

Több-bérlős webes API-k

A több-bérlős webes API-megoldásokat több bérlő, például különböző szervezetek osztják meg, amelyek saját felhasználói csoportokkal rendelkeznek.

A több-bérlősség jelentősen befolyásolja a webes API kialakítását, mivel meghatározza az erőforrások elérését és felderítését több bérlőn belül egyetlen webes API-ban. Tervezzen olyan több-bérlős API-t, amely segít elkerülni a jövőbeni refaktorálás szükségességét az elkülönítés, a méretezhetőség vagy a bérlőspecifikus testreszabások megvalósítása érdekében.

Egy jól felépítésű API-nak egyértelműen meg kell határoznia, hogyan azonosíthatók a bérlők a kérelmekben, akár altartományokon, útvonalakon, fejléceken vagy jogkivonatokon keresztül. Ez a struktúra egységes, mégis rugalmas felületet biztosít a rendszeren belüli összes felhasználó számára. További információ: Bérlőknek küldött kérelmek leképezése több-bérlős megoldásban.

A több-bérlősség hatással van a végpont szerkezetére, a kérések kezelésére, a hitelesítésre és az engedélyezésre. Ez a megközelítés azt is befolyásolja, hogy az API-átjárók, a terheléselosztók, valamint a háttérszolgáltatások hogyan irányítják és dolgozzák fel a kéréseket. Az alábbi stratégiák gyakori módszerek a több-bérlős architektúra megvalósítására egy webes API-ban.

Altartomány- vagy tartományalapú elkülönítés használata (DNS-szintű bérlés)

Ez a megközelítés bérlőspecifikus tartományok használatával irányítja a kérelmeket. A joker tartományok altartományokat használnak a rugalmasság és egyszerűség érdekében. Az egyéni tartományok, amelyek lehetővé teszik a bérlők számára a saját tartományaik használatát, nagyobb felügyeletet biztosítanak, és az adott igényeknek megfelelően testre szabhatók. Mindkét módszer a megfelelő DNS-konfigurációra támaszkodik, beleértve a rekordokat is ACNAME , hogy a forgalmat a megfelelő infrastruktúrába irányíthassa. A helyettesítő tartományok leegyszerűsítik a konfigurálást, de az egyéni tartományok védjegyesebb élményt nyújtanak.

Őrizze meg a gazdanevet a fordított proxy és a háttérszolgáltatások között, hogy elkerülje az olyan problémákat, mint az URL-átirányítás, és megakadályozza a belső URL-címek közzétételét. Ez a módszer biztosítja a bérlőspecifikus forgalom helyes útválasztását, és segít megvédeni a belső infrastruktúrát. A DNS-feloldás elengedhetetlen az adatrezidencia fenntartásához és a jogszabályi megfelelőség biztosításához.

GET https://adventureworks.api.contoso.com/orders/3

Bérlőspecifikus HTTP-fejlécek küldése

A bérlői adatok átadhatók egyéni HTTP-fejléceken keresztül, mint például X-Tenant-ID vagy X-Organization-ID, vagy gazdagépalapú fejléceken keresztül, mint például Host vagy X-Forwarded-Host, vagy pedig a JSON Web Tokenből (JWT) származó jogcímekből is kinyerhetők. A választás az API-átjáró vagy a fordított proxy útválasztási képességeitől függ, és a fejlécalapú megoldásokhoz 7. rétegbeli (L7) átjáróra van szükség az egyes kérések vizsgálatához. Ez a követelmény feldolgozási többletterhelést ad hozzá, ami növeli a számítási költségeket a forgalom skálázásakor. A fejlécalapú elkülönítés azonban kulcsfontosságú előnyökkel jár. Lehetővé teszi a központosított hitelesítést, amely leegyszerűsíti a több-bérlős API-k biztonságkezelését. SDK-k vagy API-ügyfelek használatával a bérlői környezet futásidőben dinamikusan kezelhető, ami csökkenti az ügyféloldali konfiguráció összetettségét. Emellett a bérlői környezet fejlécekben való megtartása tisztább, RESTful API-kialakítást eredményez azáltal, hogy elkerüli a bérlőspecifikus adatokat az URI-ban.

A fejlécalapú útválasztás fontos szempontja, hogy bonyolítja a gyorsítótárazást, különösen akkor, ha a gyorsítótárrétegek kizárólag URI-alapú kulcsokra támaszkodnak, és nem veszik figyelembe a fejléceket. Mivel a legtöbb gyorsítótárazási mechanizmus optimalizálja az URI-kereséseket, a fejlécekre támaszkodva töredezett gyorsítótár-bejegyzésekhez vezethet. A töredezett bejegyzések csökkentik a gyorsítótár-találatokat, és növelik a háttérbetöltést. Kritikusabb, ha a gyorsítótárazási réteg nem különbözteti meg a válaszokat fejlécek szerint, akkor képes kiszolgálni az egyik bérlőnek szánt gyorsítótárazott adatokat a másiknak, és adatszivárgás kockázatát okozhatja.

GET https://api.contoso.com/orders/3
X-Tenant-ID: adventureworks

vagy

GET https://api.contoso.com/orders/3
Host: adventureworks

vagy

GET https://api.contoso.com/orders/3
Authorization: Bearer <JWT-token including a tenant-id: adventureworks claim>

Bérlőspecifikus információk átadása az URI-útvonalon keresztül

Ez a megközelítés hozzáfűzi a bérlőazonosítókat az erőforráshierarchián belül, és az API-átjáróra vagy a fordított proxyra támaszkodik a megfelelő bérlő elérésiút-szegmens alapján történő meghatározásához. Az elérésiút-alapú elkülönítés hatékony, de rontja a webes API RESTful kialakítását, és összetettebb útválasztási logikát vezet be. Gyakran szükség van mintaegyeztetési vagy reguláris kifejezésekre az URI-elérési út elemzéséhez és canonicalizálásához.

Ezzel szemben a fejlécalapú elkülönítés kulcs-érték párokként http-fejléceken keresztül közvetíti a bérlői adatokat. Mindkét megközelítés lehetővé teszi az infrastruktúra hatékony megosztását a működési költségek csökkentése és a nagy méretű, több-bérlős webes API-k teljesítményének javítása érdekében.

GET https://api.contoso.com/tenants/adventureworks/orders/3

Elosztott nyomkövetési és nyomkövetési környezet engedélyezése API-kban

Ahogy az elosztott rendszerek és a mikroszolgáltatás-architektúrák standardtá válnak, a modern architektúrák összetettsége nő. Az API-kérésekben a nyomkövetési környezet propagálása fejlécekkel, például Correlation-ID, X-Request-ID, vagy X-Trace-ID, ajánlott eljárás a teljes körű láthatóság eléréséhez. Ez a megközelítés lehetővé teszi a kérések zökkenőmentes nyomon követését, miközben az ügyfélről a háttérszolgáltatásokra haladnak. Megkönnyíti a hibák gyors azonosítását, figyeli a késést, és leképezi az API-függőségeket a szolgáltatások között.

A nyomkövetési és környezeti információk felvételét támogató API-k növelik a megfigyelhetőségi szintet és a hibakeresési képességeket. Az elosztott nyomkövetés engedélyezésével ezek az API-k részletesebben értelmezik a rendszer viselkedését, és megkönnyítik a problémák nyomon követését, diagnosztizálását és megoldását összetett, többszolgáltatásos környezetekben.

GET https://api.contoso.com/orders/3
Correlation-ID: 0f8fad5b-d9cb-469f-a165-70867728950e

HTTP/1.1 200 OK
...
Correlation-ID: 0f8fad5b-d9cb-469f-a165-70867728950e

{...}

API fejlettségi modell

2008-ban Leonard Richardson javasolta a richardsoni lejárati modell (RMM) nevet a webes API-khoz. Az RMM négy fejlettségi szintet határoz meg a webes API-k esetében, és a REST alapelvein alapul, mint a webszolgáltatások tervezésének architekturális megközelítésén. Az RMM-ben, ahogy növekszik az érettségi szint, az API egyre RESTfulabbá válik és jobban követi a REST alapelveit.

A szintek a következők:

  • 0. szint: Definiáljon egy URI-t, és minden művelet POST-kérés ehhez az URI-hoz. Az Egyszerű objektumhozzáférés protokoll webszolgáltatásai általában ezen a szinten vannak.
  • 1. szint: Hozzon létre külön URI-kat az egyes erőforrásokhoz. Ez a szint még nem RESTful, de elkezd igazodni a RESTful kialakításhoz.
  • 2. szint: HTTP-metódusokkal definiálhat műveleteket az erőforrásokon. A gyakorlatban számos közzétett webes API nagyjából ehhez a szinthez igazodik.
  • 3. szint: Használja a hypermedia-t (HATEOAS). Ez a szint valóban RESTful API, a Fielding definíciója szerint.

OpenAPI-kezdeményezés

Az OpenAPI-kezdeményezést egy iparági konzorcium hozta létre, hogy szabványosítsa a REST API-leírásokat a gyártók között. A szabványosítási specifikáció neve Swagger volt, mielőtt az OpenAPI-kezdeményezés alá került volna, és átnevezték az OpenAPI-specifikációra (OAS).

Érdemes lehet openAPI-t alkalmazni a RESTful webes API-khoz. Vegye figyelembe a következő szempontokat:

  • Az OAS a REST API tervezésére vonatkozó véleményezett irányelveket tartalmaz. Az irányelvek előnyösek az együttműködés szempontjából, de megkövetelik, hogy a kialakítás megfeleljen a specifikációknak.

  • Az OpenAPI egy szerződés-első megközelítést támogat implementáció-első megközelítés helyett. A szerződés-első azt jelenti, hogy először az API-szerződést (az interfészt) kell megtervezni, majd írni a szerződést megvalósító kódot.

  • Az olyan eszközök, mint a Swagger (OpenAPI) ügyfélkódtárakat vagy dokumentációkat hozhatnak létre API-szerződésekből. Példa: ASP.NET Core webes API dokumentációja a Swagger/OpenAPI használatával.

Következő lépések