Formato das respostas

Todas as respostas são JSON (application/json). O formato do corpo varia conforme o endpoint: alguns retornam um array direto, outros um objeto único e outros um envelope com metadados de paginação.

Três formatos de corpo

Vale conhecer os três padrões antes de integrar, porque cada um pede um consumo diferente:

1. Array direto

Listagens simples retornam um array no nível raiz, sem envelope. Usado por GET /public/posts, GET /public/categories e GET /public/tags.

[
  { "id": "clxxx101", "title": "Primeiro post", "slug": "primeiro-post", "status": "PUBLISHED" },
  { "id": "clxxx102", "title": "Segundo post", "slug": "segundo-post", "status": "PUBLISHED" }
]

2. Objeto único

Buscas por identificador retornam o recurso diretamente. Usado por GET /public/posts/{id}, /slug/{slug}, /public/categories/{id} e /public/tags/{id}.

{
  "id": "clxxx201",
  "name": "Tecnologia",
  "description": "Posts sobre tecnologia",
  "blogId": "clxxx789",
  "_count": { "posts": 5 }
}

3. Envelope com paginação

Listagens paginadas retornam um objeto envelope. As listagens de posts por categoria e por tag usam o envelope PostListResponse; a busca usa SearchResponse (com data e meta). Veja Paginação.

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

Tipos e convenções

Formato de erro

Respostas de erro seguem um objeto simples com error e, quando disponível, message. Veja Tratamento de erros para detalhes.

{
  "error": "Mensagem de erro",
  "message": "Descrição detalhada do erro"
}

Charset e codificação

• Respostas são UTF-8. Acentuação e emojis são preservados.
• O campo content dos posts pode conter HTML ou Markdown, conforme produzido no editor — trate-o de acordo ao renderizar.