HTTP API: hibák, gyorsítótár, konkurencia és hosszú műveletek

Célok

A lecke végére el tudod magyarázni, hogyan kezel egy használható HTTP API hibákat, gyorsítótárat, konkurens módosítást és hosszú műveleteket.

Miért kell?

Egy API nemcsak a sikeres esetre készül. A fogyasztónak meg kell tudnia különböztetni a hibás bemenetet, a hiányzó erőforrást, az ütközést, a túlterhelést és az átmeneti függőségi hibát; és tudnia kell, mi történik, ha ketten módosítanak egyszerre.

Hibák: státusz és részletek

A státuszkód a hiba osztályát jelzi: a 400 hibás kérés, 401 hiányzó vagy hibás hitelesítés, 403 tiltott hozzáférés, 404 nem található, 409 ütközés, 412 sikertelen előfeltétel, 429 túl sok kérés (RFC 6585), 503 átmeneti túlterhelés vagy karbantartás (RFC 9110, Retry-After fejléccel). A 201 létrehozott erőforrást, a 202 elfogadott, de be nem fejezett feldolgozást jelent.

A géppel kezelhető részletekhez az RFC 9457 problem details formátuma szolgál (application/problem+json), amelynek tagjai: type, title, status, detail, instance. A kliens ne emberi mondatokat hasonlítson össze: a stabil hibakód programozottan kezelhető, a megjelenített szöveg változhat. A hibaválasz ne közöljön belső nyomkövetést vagy titkos konfigurációt.

Gyorsítótár és feltételes olvasás

A gyorsítótár csökkenti az ismételt kérés költségét, de meg kell adni a frissesség és a megoszthatóság szabályait: egy nyilvános katalógus más kezelést igényel, mint egy személyes lista. Az ETag az erőforrás-reprezentáció verzióját azonosítja. A kliens If-None-Match fejléccel jelezheti, hogy már ismeri a verziót; változatlan állapotnál a szerver 304-et adhat (feltételes kérés). Ez kevesebb adatátvitelt jelent, de nem teszi költségmentessé a szerveroldali ellenőrzést.

Konkurens módosítás

Ha két kliens ugyanazt a régi állapotot olvasta, a második módosítás felülírhatja az elsőt. A feltételes írás (If-Match az ETag-gel) csak akkor sikerül, ha a kliens ismert verziója még aktuális; különben a szerver 412-vel válaszol. Az ellenőrzést és az írást a szervernek együtt kell érvényesítenie.

sequenceDiagram
  participant A as Kliens A
  participant B as Kliens B
  participant S as Szolgáltatás
  A->>S: GET
  S-->>A: 7. verzió
  B->>S: GET
  S-->>B: 7. verzió
  A->>S: Módosítás, If-Match 7
  S-->>A: Siker, 8. verzió
  B->>S: Módosítás, If-Match 7
  S-->>B: 412, a verzió megváltozott

Az ütközés után a kliens újraolvashatja az állapotot, és dönthet. Az automatikus újraküldés a friss verzióval felülírhatja a másik módosítását jóváhagyás nélkül.

Hosszú művelet

Egy nagy műveletet nem szükséges nyitott kérésben megvárni. A 202 Accepted az RFC szerint „szándékosan nem elkötelezett”: a válasz írja le az aktuális állapotot, és egy állapotfigyelőre mutat. A szerződésnek rögzítenie kell az eredmény helyét, a hibát, a lejáratot és a megszakítás lehetőségét; a kliens állapotot kérdez (polling, 9.1) vagy értesítést kap (8.5, 9.3).

Lapozás

A listáknál a lapozás korlátozza a válasz méretét. Az offset egyszerű, de változó adathalmazban az elemek eltolódhatnak. A cursor egy megállapodott rendezési pontot jelöl; stabil rendezéshez azonosítóval kiegészített rendezési kulcs kell.

Gyakori tévhitek

Állítás	Pontosítás
„A 200 minden sikert jelent.”	A 201, 202, 204 más jelentésű sikerek.
„Az ETag csak a gyorsítótárhoz kell.”	Konkurenciakezelésre is használható (If-Match).
„A lapozásnál az offset mindig jó.”	Változó adatnál eltolódhat; a cursor stabilabb.
„A hibaüzenet szövege a szerződés.”	A kód a szerződés; a szöveg változhat.

Röviden

• A státusz a hiba osztályát, a problem details a részleteket adja.
• Az ETag és a feltételes kérés kevesebb adatátvitelt és biztonságos írást tesz lehetővé.
• A 202 hosszú műveletet jelez; a szerződés megadja az állapotlekérdezést.
• Lapozásnál a cursor stabilabb az offsetnél.

Ellenőrző kérdések

1. Mit jelent a 412, és mikor jelenik meg?
2. Miért veszélyes az automatikus újraküldés ütközés után?
3. Hogyan fejezhet ki egy API hosszú műveletet?

Források

• RFC 9110, 15.3.3: 202 Accepted
• RFC 9457: Problem Details for HTTP APIs — géppel kezelhető hibaformátum.
• RFC 6585: Additional HTTP Status Codes — a 429 Too Many Requests meghatározása.