Egy API-listázás száz rekordot ad vissza. Ez lehet a teljes adatállomány, de lehet a több ezer elemes lista első oldala is. Teljes exporthoz a lapozási szabályt, a rendezést és a feldolgozás végének jelzését egyaránt ismerni kell. A sikeres HTTP-válasz egyetlen kérés eredményét igazolja.
A következő számpéldák egy feltételezett API-val dolgoznak. Az oldalméret, a lapozási paraméter és a lezáró jelzés szolgáltatónként eltérhet.
Hány oldalra számíts?
Tegyük fel, hogy 235 rekordot kell lekérni, az oldalméret legfeljebb 100. A szükséges oldalak száma a 235 / 100 hányados felfelé kerekítése: 3 oldal. A három oldal rendre 100, 100 és 35 rekordot tartalmaz.
Oldalszám = teljes rekordszám / oldalméret, felfelé kerekítve.
Eltolásos lapozásnál a kezdő eltolások ebben a példában 0, 100 és 200. A limit a legfeljebb visszakért mennyiség, az offset a kihagyott rekordok száma. Ez a szóhasználat gyakori, de mindig az adott API dokumentációja az irányadó.
A PostgreSQL LIMIT és OFFSET dokumentációja az ilyen részhalmazoknál hangsúlyozza az egyértelmű rendezés jelentőségét. Ez adatbázis-dokumentáció, az API viselkedését külön meg kell vizsgálni; az alapvető sorrendi probléma viszont ugyanúgy megjelenhet az API mögötti listázásban.
Az utolsó teljes oldal után mi történik?
Ha pontosan 200 rekord van és az oldalméret 100, két teljes oldal érkezik. Az „akkor állj meg, ha kevesebb jött száz tételnél” szabály ilyenkor egy harmadik, üres lekérést is igényelhet. Ha az API megbízható has_more mezőt vagy következő oldalra mutató jelzést ad, az alapján is lezárható a lapozás.
A Stripe lapozási leírása például kurzoros működést dokumentál. A kurzor a következő részlet helyét a már látott objektumhoz köti. Ez eltér az előző bekezdés hipotetikus offset-megoldásától. A visszakapott kurzort változatlanul kell a dokumentált módon továbbadni.
A rövid oldal önmagában csak akkor lezáró bizonyíték, ha ezt a szolgáltató garantálja. Egyes rendszerek a kért maximumnál kevesebbet is visszaadhatnak úgy, hogy marad további adat. Az export befejezési feltételét ezért szövegesen is rögzítsd.
Mi történik, ha közben új rekord érkezik?
A lista növekvő helyett most csökkenő időrendű. Az első lekérés A, B, C rekordot ad vissza. A következő kérés előtt X kerül a lista elejére, így a sorrend X, A, B, C, D, E lesz. Három elem kihagyása után a második oldal C, D, E. C kétszer jelenik meg, X pedig kimarad az addig látott listából.
A két oldal együtt hat visszakapott rekordot, de csak öt egyedi azonosítót tartalmaz. A duplikált rekord kiszűrése szükséges lehet, ám a közben kimaradt X-et nem hozza vissza. A darabszám egyezése sem teljes bizonyíték, ha a forrás közben változik.
Teljes pillanatképhez használj dokumentált snapshot-mechanizmust, rögzített lekérdezési határt vagy az adott rendszer által biztosított következetes exportot. A kurzor csökkenthet egyes eltolási problémákat, de önmagában nem garantál minden rendszerben változatlan pillanatképet.
Négy szám az import végén
Érdemes külön feljegyezni a lekért oldalak számát, az összes visszakapott rekordot, az egyedi azonosítók számát és az elfogadott rekordokat. Például 235 visszakapott sorból 232 egyedi azonosító és 230 elfogadott tétel esetén három ismétlődés és további két elutasított egyedi rekord vizsgálata szükséges, ha minden ismétlődés egy többletpéldány.
A többféle számláló segít elválasztani a lapozási hibát a validálási hibától. A számok mellé az export kezdő és befejező időpontja, a szűrés és a rendezés is kerüljön. Az azonosítók lehetőleg stabil, egyedi értékek legyenek; a megjelenített név ritkán alkalmas erre.
A JSON-formázó a válasz mezőinek áttekintéséhez, a JSON-összehasonlító két oldal vagy export összevetéséhez adhat általános segítséget. A teljes lista ellenőrzése ezek mellett a dokumentált lapozási szerződést és a saját számlálókat igényli.
Tudáspróba
1. Hány oldal szükséges 235 rekordhoz, százrekordos oldalmérettel?
- A: 2.
- B: 3.
- C: 235.
2. Mi történik a bemutatott X, A, B, C, D, E listán háromelemnyi offset után?
- A: C, D, E érkezik, így C ismétlődik a korábbi oldalhoz képest.
- B: A lista automatikusan változatlan pillanatképpé válik.
- C: X biztosan szerepel a második oldalon.
3. Mit kell ellenőrizni egy rövid oldal miatti leállítás előtt?
- A: A JSON behúzásának szélességét.
- B: Kizárólag az első rekord nevét.
- C: Az API dokumentált befejezési feltételét.
Megoldások és következő lépés
1. B. Két teljes és egy 35 rekordos oldal kell.
2. A. Az új első elem eltolja a pozíciókat, ezért a második kérés C-t újra látja.
3. C. A maximumnál rövidebb oldal egyes rendszerekben további adat mellett is előfordulhat.
0–1 pont: számold végig a 0, 100 és 200 eltolású példát. 2 pont: különítsd el a visszakapott és az egyedi rekordszámot. 3 pont: saját exportodhoz dokumentáld a rendezést, a lezáró feltételt és a közben változó forrás kezelését.
