Stránkovací parametry (pagination parameters)

Příklady z praxe

1. 01

   Offsetový výpis v REST API

   E-shop vypisuje objednávky přes endpoint /api/orders. Klient pošle page a limit, server hodnoty ověří, ořízne limit na 100 a dopočítá offset. V odpovědi vrací kromě položek i celkový počet, protože tabulka objednávek jednoho zákazníka je malá a COUNT je zde levný.

   const page  = Math.max(1, Number(req.query.page) || 1);
   const limit = Math.min(100, Number(req.query.limit) || 20);
   const rows = await db.query(
     'SELECT id, total, created_at FROM orders WHERE customer_id = $1 ORDER BY id DESC LIMIT $2 OFFSET $3',
     [customerId, limit, (page - 1) * limit]
   );

2. 02

   Kurzor u nekonečného scrollu

   Feed příspěvků v mobilní aplikaci se donačítá při scrollování a nová data přibývají každou minutu. Offsetové stránkování by způsobilo duplicity, proto server vrací cursor sestavený z dvojice (created_at, id) posledního záznamu. Další požadavek ho pošle zpět jako parametr after a dotaz sáhne rovnou na index.

   SELECT id, body, created_at
   FROM posts
   WHERE (created_at, id) < ($1, $2)
   ORDER BY created_at DESC, id DESC
   LIMIT 20;

Časté omyly

MýtusStránkování je jen LIMIT a OFFSET, na tom se nedá nic pokazit.

Ve skutečnostiOffsetové stránkování nad měnícími se daty vynechává a duplikuje záznamy a s rostoucím offsetem lineárně zpomaluje, protože databáze musí přeskakované řádky přesto načíst. U velkých nebo živých seznamů je kurzorové stránkování spolehlivější.

MýtusStránky 2 a dál by měly mít kanonickou URL na stránku 1.

Ve skutečnostiStránka 2 obsahuje jiné položky, takže kanonizace na stránku 1 vede k tomu, že se její obsah přestane indexovat. Každá stránka výpisu má být kanonická sama na sebe; kanonizovat se mají jen adresy lišící se nepodstatnými parametry.

MýtusKdyž klient pošle limit=100000, je to jeho problém.

Ve skutečnostiNeomezený limit je vektor pro odepření služby: jediný požadavek dokáže vyčerpat paměť aplikace i spojení do databáze. Server musí mít vlastní tvrdý strop nezávisle na tom, co klient požaduje.

Časté dotazy

Jak pojmenovat stránkovací parametry v REST API?

Stránkovací parametry se v praxi nejčastěji pojmenovávají page a limit, offset a limit nebo cursor a limit. Konkrétní volba je méně důležitá než konzistence napříč celým API: pokud jeden endpoint používá per_page a druhý pageSize, integrace se zbytečně komplikuje. Vyplatí se držet malá písmena a jedno oddělovací schéma, doplnit rozumnou výchozí hodnotu limitu a v dokumentaci uvést i maximum, které server akceptuje. U kurzorů je zvykem hodnotu považovat za neprůhlednou, tedy klientovi zakázat její vlastní skládání.

Proč je vysoký offset v databázi pomalý?

Vysoký offset je pomalý proto, že klauzule OFFSET nepřeskočí řádky zdarma. Databáze musí odpovídající záznamy najít, seřadit a teprve pak zahodit, takže dotaz s OFFSET 500000 udělá zhruba stejnou práci jako dotaz vracející půl milionu řádků. Náklady rostou lineárně s hloubkou stránky. Kurzorové stránkování tento problém obchází podmínkou na hodnoty posledního viděného záznamu, kterou index dokáže vyhodnotit přímo, takže doba odpovědi zůstává stejná na první i na tisící stránce.

Mají mít stránkovací parametry vliv na indexaci vyhledávači?

Stránkovací parametry mají na indexaci zásadní vliv, protože každá kombinace tvoří samostatnou URL. Doporučený postup je nechat jednotlivé stránky výpisu indexovatelné, ale zamezit vzniku duplicit z nepodstatných parametrů, například řazení nebo tracking kódů. Pomáhá pevné pořadí parametrů v odkazech, kanonická URL u ekvivalentních variant a odkazy na další a předchozí stránku v HTML, aby robot výpis prošel celý. Stránky za rozumnou hloubkou se často z procházení vyřazují, protože jejich obsah je pro vyhledávání málo hodnotný.

Jak stránkovat, když uživatel potřebuje skákat na konkrétní stránku?

Skoky na konkrétní stránku vyžadují offsetové stránkování, protože kurzor zná jen pozici posledního načteného záznamu. Kompromisem je nabídnout číslované stránky jen do určité hloubky, například do padesáté stránky, a hlubší navigaci nahradit filtry, fulltextem nebo řazením. Uživatel, který hledá konkrétní záznam na stránce 300, ho stejně najde rychleji vyhledáním. Druhou možností je předpočítat hranice stránek do pomocné tabulky, což se vyplatí u dat, která se mění zřídka.

Patří stránkovací parametry do URL, nebo do těla požadavku?

Stránkovací parametry patří u operací čtení do query stringu URL. Odpověď zůstane cacheovatelná, adresa jde sdílet a zalogovat a chování odpovídá tomu, že GET nemá mít tělo s významem. Do těla se stránkování posouvá jen tam, kde je samotný dotaz složitý a posílá se metodou POST, typicky u vyhledávání s mnoha filtry nebo u GraphQL. I v takovém případě je vhodné argumenty pojmenovat stejně jako v REST části API.

Zdroje

1. URL Standard(otevře se v novém okně)WHATWG
2. LIMIT and OFFSET(otevře se v novém okně)PostgreSQL Global Development Group
3. cursor.skip()(otevře se v novém okně)MongoDB
4. Pagination(otevře se v novém okně)Stripe
5. Google Search Central: URL structure best practices(otevře se v novém okně)Google

Související pojmy

• Kanonická URLKanonická URL je adresa, kterou vlastník webu označuje jako hlavní verzi stránky s totožným nebo velmi podobným obsahem. Vyhledávače ji používají jako silný signál při výběru URL pro indexaci a výsledky hledání, aby se hodnocení, odkazy a metriky netříštily mezi více variant.
• Rate limitingRate limiting je řízení toho, kolik požadavků, akcí nebo událostí smí klient provést za určité období. Používá se u API, webových aplikací i interních služeb, aby chránilo kapacitu systému, zpomalilo zneužití a rozdělilo dostupné zdroje spravedlivěji mezi uživatele, aplikace nebo IP adresy.
• REST APIREST API je způsob návrhu webového rozhraní, kde klient pracuje se zdroji přes jednotné HTTP operace a server vrací jejich reprezentace, typicky ve formátu JSON. Důraz klade na jednoznačné adresy, bezstavovou komunikaci, cachování a oddělení klienta od serveru, ne na konkrétní knihovnu ani protokol navíc.
• 3D model3D model je digitální reprezentace objektu nebo prostoru ve třech rozměrech, složená z geometrie, materiálů a často i textur, animací či fyzikálních vlastností. Používá se v hrách, filmech, průmyslovém návrhu, architektuře, e-commerce i simulacích, kde software z modelu počítá zobrazení nebo další data.
• ACIDACID je sada čtyř vlastností databázové transakce: atomicity, consistency, isolation a durability. Zaručuje, že skupina zápisů proběhne jako jeden celek, neporuší definovaná pravidla databáze, nebude se nebezpečně míchat s jinými transakcemi a po potvrzení přežije pád systému, například při převodu peněz.
• Adaptive IconAdaptivní ikona je formát ikony aplikace na Androidu, který se místo jedné hotové bitmapy skládá z oddělených vrstev: pozadí a popředí. Systém výsledný tvar sám ořízne podle masky výrobce zařízení a může vrstvy animovat nebo přebarvit. Vývojář tak dodá jeden zdroj a launcher z něj vytvoří kruh, čtverec i squircle.
• Adresa v pamětiAdresa v paměti je číslo, kterým procesor jednoznačně označuje konkrétní buňku operační paměti, obvykle jeden bajt. Program pomocí adresy říká, odkud má data načíst nebo kam je zapsat. Adresy tvoří souvislý číselný rozsah, jehož velikost určuje šířka adresní sběrnice a architektura, typicky 32 nebo 64 bitů.
• AI agentAI agent je softwarový systém, který pomocí modelu umělé inteligence vnímá zadaný kontext, plánuje další kroky a samostatně volá nástroje nebo služby k dosažení cíle. Na rozdíl od jednorázového promptu udržuje stav úlohy, vyhodnocuje výsledky akcí a může opakovat postup, dokud nesplní zadání nebo nenarazí na limit.