Fundamentos

Paginação

A API pública usa três convenções de paginação dependendo do endpoint. Conhecer a diferença evita surpresas — especialmente porque uma delas retorna um array puro, sem total.

Visão geral

Endpoint	Parâmetros	Formato de retorno
`GET /public/posts`	`limit` (1–100, padrão 10) `offset` (≥ 0)	Array de `Post` (sem total)
`GET /public/categories/{id}/posts` `GET /public/tags/{id}/posts`	`page` (padrão 1) `pageSize` (padrão 10)	Envelope `PostListResponse`
`GET /public/search`	`limit` (padrão 10, máx 50) `offset` (padrão 0)	Envelope `SearchResponse` (`data` + `meta`)

Estilo A — limit / offset (array puro)

Em GET /public/posts, limit define o tamanho da página (máximo 100) e offset quantos itens pular. A resposta é um array — não há contagem total, então você detecta o fim quando um lote retorna menos itens que o limite.

Requisição

# Página 1 (itens 0–9)
curl "https://api.draftin.io/public/posts?limit=10&offset=0" -H "X-API-Key: $DRAFTIN_API_KEY"

# Página 2 (itens 10–19)
curl "https://api.draftin.io/public/posts?limit=10&offset=10" -H "X-API-Key: $DRAFTIN_API_KEY"

TypeScript

// Percorre TODOS os posts publicados com limit/offset.
const BASE = "https://api.draftin.io";
const headers = { "X-API-Key": process.env.DRAFTIN_API_KEY! };
const PAGE = 50; // máximo permitido: 100

const all: unknown[] = [];
for (let offset = 0; ; offset += PAGE) {
  const res = await fetch(`${BASE}/public/posts?limit=${PAGE}&offset=${offset}`, { headers });
  const batch = (await res.json()) as unknown[];
  all.push(...batch);
  if (batch.length < PAGE) break; // última página: veio menos que o limite
}

console.log(`${all.length} posts no total`);

Estilo B — page / pageSize (envelope)

As listagens de posts por categoria e por tag usam page (começando em 1) e pageSize. A resposta inclui os metadados que você precisa para construir uma paginação numerada:

200 OK

{
  "posts": [ /* … */ ],
  "total": 42,
  "page": 1,
  "pageSize": 10,
  "totalPages": 5
}

TypeScript

// Percorre os posts de uma categoria com page/pageSize.
const BASE = "https://api.draftin.io";
const headers = { "X-API-Key": process.env.DRAFTIN_API_KEY! };

interface PostListResponse {
  posts: { id: string; title: string }[];
  total: number;
  page: number;
  pageSize: number;
  totalPages: number;
}

async function postsDaCategoria(categoryId: string) {
  const out: PostListResponse["posts"] = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await fetch(
      `${BASE}/public/categories/${categoryId}/posts?page=${page}&pageSize=20`,
      { headers },
    );
    const data = (await res.json()) as PostListResponse;
    out.push(...data.posts);
    totalPages = data.totalPages;
    page++;
  } while (page <= totalPages);

  return out;
}

Estilo C — busca paginada

GET /public/search usa limit (padrão 10, máximo 50) e offset (padrão 0). A resposta traz os resultados em data e os metadados em meta, incluindo count (quantidade nesta página) e o termo q usado:

200 OK

{
  "data": [ /* … resultados … */ ],
  "meta": { "q": "javascript", "limit": 10, "offset": 0, "count": 5 }
}