Endpoints · Categorias

Categorias

Categorias organizam o conteúdo do blog em grandes temas. Use estes endpoints para montar menus, páginas de seção e índices temáticos. Cada categoria traz a contagem de posts em _count.posts.

Listar categorias

GET https://api.draftin.io /public/categories

Requer X-API-Key

Retorna todas as categorias do blog em data (array). Ideal para construir a navegação por temas e exibir quantos posts cada categoria contém.

Quando usar

Renderizar um menu ou nuvem de categorias.
Gerar páginas de seção (uma por categoria).
Mostrar a contagem de posts ao lado de cada tema.

Exemplo de requisição

curl "https://api.draftin.io/public/categories" \
  -H "X-API-Key: $DRAFTIN_API_KEY"

const res = await fetch("https://api.draftin.io/public/categories", {
  headers: { "X-API-Key": process.env.DRAFTIN_API_KEY },
});
const { data: categories } = await res.json(); // Category[]

import type { Category } from "./types";

async function listarCategorias(): Promise<Category[]> {
  const res = await fetch("https://api.draftin.io/public/categories", {
    headers: { "X-API-Key": process.env.DRAFTIN_API_KEY! },
  });
  if (!res.ok) throw new Error(`DraftIn API: ${res.status}`);
  const { data } = (await res.json()) as { data: Category[] };
  return data;
}

const res = await fetch("https://api.draftin.io/public/categories", {
  headers: { "X-API-Key": process.env.DRAFTIN_API_KEY },
});
const { data: categorias } = await res.json();
// monta um menu de navegação com a contagem de posts
console.table(categorias.map((c) => ({ nome: c.name, posts: c._count?.posts ?? 0 })));

Exemplo de resposta

200 OK — { success, data: Category[] }

{
  "success": true,
  "data": [
    {
      "id": "clxxx201",
      "name": "Tecnologia",
      "description": "Posts sobre tecnologia",
      "blogId": "clxxx789",
      "createdAt": "2026-05-01T10:00:00.000Z",
      "updatedAt": "2026-05-20T14:30:00.000Z",
      "_count": { "posts": 5 }
    }
  ]
}

Respostas possíveis

Status	Significado
200 OK	Lista de categorias (`data`: array de `Category`).
401 Unauthorized	Chave de API inválida ou ausente.
500 Internal Server Error	Erro interno; repita com backoff.

Obter categoria por ID

GET https://api.draftin.io /public/categories/{id}

Requer X-API-Key

Recupera uma única categoria pelo seu identificador — por exemplo, para o cabeçalho de uma página de seção.

Parâmetros de rota

Parâmetro	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador único da categoria.

Exemplo de requisição

curl "https://api.draftin.io/public/categories/clxxx201" \
  -H "X-API-Key: $DRAFTIN_API_KEY"

const id = "clxxx201";
const res = await fetch(`https://api.draftin.io/public/categories/${id}`, {
  headers: { "X-API-Key": process.env.DRAFTIN_API_KEY },
});
const category = res.ok ? (await res.json()).data : null;

async function getCategoria(id: string): Promise<Category | null> {
  const res = await fetch(`https://api.draftin.io/public/categories/${id}`, {
    headers: { "X-API-Key": process.env.DRAFTIN_API_KEY! },
  });
  if (res.status === 404) return null;
  if (!res.ok) throw new Error(`DraftIn API: ${res.status}`);
  const { data } = (await res.json()) as { data: Category };
  return data;
}

Exemplo de resposta

200 OK — { success, data: Category }

{
  "success": true,
  "data": {
    "id": "clxxx201",
    "name": "Tecnologia",
    "description": "Posts sobre tecnologia",
    "blogId": "clxxx789",
    "createdAt": "2026-05-01T10:00:00.000Z",
    "updatedAt": "2026-05-20T14:30:00.000Z",
    "_count": { "posts": 5 }
  }
}

Respostas possíveis

Status	Significado
200 OK	Categoria encontrada (`data`: objeto `Category`).
401 Unauthorized	Chave de API inválida ou ausente.
404 Not Found	Categoria não encontrada.
500 Internal Server Error	Erro interno; repita com backoff.

Listar posts de uma categoria

GET https://api.draftin.io /public/categories/{id}/posts

Requer X-API-Key

Retorna os posts publicados pertencentes à categoria, paginados por page/pageSize. Os itens vêm em data e os metadados de contagem em meta.pagination — prontos para uma paginação numerada.

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
id	string	Sim	ID da categoria. (parâmetro de rota)
page	integer	Não	Número da página (começa em 1). Padrão: `1`
pageSize	integer	Não	Quantidade de posts por página. Padrão: `10`

Exemplo de requisição

curl "https://api.draftin.io/public/categories/clxxx201/posts?page=1&pageSize=10" \
  -H "X-API-Key: $DRAFTIN_API_KEY"

const id = "clxxx201";
const res = await fetch(
  `https://api.draftin.io/public/categories/${id}/posts?page=1&pageSize=10`,
  { headers: { "X-API-Key": process.env.DRAFTIN_API_KEY } },
);
const { data: posts, meta } = await res.json();
console.log(meta.pagination.total, "posts na categoria");

import type { Envelope, Post } from "./types";

async function postsDaCategoria(id: string, page = 1, pageSize = 10) {
  const url = new URL(`/public/categories/${id}/posts`, "https://api.draftin.io");
  url.searchParams.set("page", String(page));
  url.searchParams.set("pageSize", String(pageSize));

  const res = await fetch(url, {
    headers: { "X-API-Key": process.env.DRAFTIN_API_KEY! },
  });
  if (!res.ok) throw new Error(`DraftIn API: ${res.status}`);
  return (await res.json()) as Envelope<Post[]>; // data + meta.pagination
}

Exemplo de resposta

200 OK — { success, data, meta.pagination }

{
  "success": true,
  "data": [
    {
      "id": "clxxx101",
      "title": "Meu Primeiro Post",
      "slug": "meu-primeiro-post",
      "status": "PUBLISHED",
      "publishedAt": "2026-06-01T12:00:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "total": 5,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPrevPage": false
    }
  }
}

Respostas possíveis

Status	Significado
200 OK	Posts da categoria (`data`: array de `Post`; `meta.pagination` canônico).
400 Bad Request	Parâmetros de paginação inválidos (`page`/`pageSize`).
401 Unauthorized	Chave de API inválida ou ausente.
404 Not Found	Categoria não encontrada.
500 Internal Server Error	Erro interno; repita com backoff.

Campos do objeto Category

idstring

Identificador único da categoria.

namestring

Nome de exibição (ex.: Tecnologia).

descriptionstring

Descrição da categoria.

blogIdstring

ID do blog dono da categoria.

createdAtstring · date-time

Data/hora de criação.

updatedAtstring · date-time

Data/hora da última atualização.

_countobject

Contadores agregados. Contém posts (integer): quantidade de posts associados a esta categoria.

Boas práticas

Use _count.posts para ocultar categorias vazias ou ordenar por popularidade.
Cacheie a lista de categorias — ela muda raramente e costuma aparecer em todas as páginas.
Pagine as seções grandes com pageSize moderado e use meta.pagination.totalPages para a navegação.

Casos de uso comuns

Menu temático: /public/categories no layout global.
Página de seção: /public/categories/{id} para o cabeçalho + /public/categories/{id}/posts para a lista.