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 um array com todas as categorias do blog. 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 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}`);
  return res.json() as Promise<Category[]>;
}

const res = await fetch("https://api.draftin.io/public/categories", {
  headers: { "X-API-Key": process.env.DRAFTIN_API_KEY },
});
const 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 — Category[]

[
  {
    "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 (array de `Category`).
401 Unauthorized	Chave de API inválida ou ausente.

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() : 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}`);
  return res.json() as Promise<Category>;
}

Exemplo de resposta

200 OK — Category

{
  "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 (objeto `Category`).
401 Unauthorized	Chave de API inválida ou ausente.
404 Not Found	Categoria não encontrada.

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. A resposta vem em um envelope PostListResponse com metadados 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 { posts, total, totalPages } = await res.json();

import type { PostListResponse } 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 res.json() as Promise<PostListResponse>;
}

Exemplo de resposta

200 OK — PostListResponse

{
  "posts": [
    {
      "id": "clxxx101",
      "title": "Meu Primeiro Post",
      "slug": "meu-primeiro-post",
      "status": "PUBLISHED",
      "publishedAt": "2026-06-01T12:00:00.000Z"
    }
  ],
  "total": 5,
  "page": 1,
  "pageSize": 10,
  "totalPages": 1
}

Respostas possíveis

Status	Significado
200 OK	Posts da categoria (envelope `PostListResponse`).
401 Unauthorized	Chave de API inválida ou ausente.

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 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.