Fundamentos

Paginação

Todos os endpoints paginados retornam os itens em data, dentro do envelope de sucesso. O que varia são os parâmetros (limit/offset ou page/pageSize) e a presença dos metadados de contagem.

Visão geral

Endpoint	Parâmetros	Metadados de contagem
`GET /public/posts`	`limit` (1–100, padrão 10) `offset` (≥ 0)	Nenhum — `data` vem sem contagem total.
`GET /public/categories/{id}/posts` `GET /public/tags/{id}/posts`	`page` (padrão 1) `pageSize` (padrão 10)	`meta.pagination` canônico (total, páginas, has*Page).
`GET /public/search`	`limit` (padrão 10, máx 50) `offset` (padrão 0)	`count` da página atual (dentro de `data.meta`).

Estilo A — limit / offset (sem contagem total)

Em GET /public/posts, limit define o tamanho da página (máximo 100) e offset quantos itens pular. A resposta traz os posts em data, sem contagem total — 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 { data: batch } = (await res.json()) as { data: 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 (meta.pagination canônico)

As listagens de posts por categoria e por tag usam page (começando em 1) e pageSize. A resposta traz os itens em data e os metadados em meta.pagination, no formato canônico PaginationMetaCanonical:

pageinteger

Página atual (começa em 1).

pageSizeinteger

Itens por página.

totalinteger

Total de itens na coleção.

totalPagesinteger

Número total de páginas.

hasNextPageboolean

Há uma próxima página?

hasPrevPageboolean

Há uma página anterior?

200 OK

{
  "success": true,
  "data": [ /* … objetos Post … */ ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "total": 42,
      "totalPages": 5,
      "hasNextPage": true,
      "hasPrevPage": false
    }
  }
}

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 Page {
  data: { id: string; title: string }[];
  meta: { pagination: { hasNextPage: boolean } };
}

async function postsDaCategoria(categoryId: string) {
  const out: Page["data"] = [];

  for (let page = 1; ; page++) {
    const res = await fetch(
      `${BASE}/public/categories/${categoryId}/posts?page=${page}&pageSize=20`,
      { headers },
    );
    const { data, meta } = (await res.json()) as Page;
    out.push(...data);
    if (!meta.pagination.hasNextPage) break;
  }

  return out;
}

Estilo C — busca paginada

GET /public/search usa limit (padrão 10, máximo 50) e offset (padrão 0). Dentro do envelope, data é um objeto SearchResponse com os resultados em data.data e os metadados em data.meta, incluindo count (quantidade nesta página) e o termo q:

200 OK

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