Busca
A busca faz uma pesquisa textual (full-text) sobre título e subtítulo dos posts publicados do blog. É a base para um campo de pesquisa no seu site, retornando resultados enxutos e prontos para listar.
Buscar posts
GET https://api.draftin.io /public/search
Requer X-API-Key
Pesquisa posts publicados por título/subtítulo. Exige um termo (q) com no mínimo
3 caracteres e retorna, dentro do envelope de sucesso, um objeto SearchResponse em data — com os resultados
em
data.data e os metadados em data.meta.
Quando usar
- Alimentar um campo de busca no cabeçalho ou em uma página dedicada.
- Oferecer autocomplete de artigos (lembre o mínimo de 3 caracteres).
- Listar resultados com capa e data sem precisar carregar o post inteiro.
Query parameters
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| q | string | Sim | Termo de busca. Mínimo de 3 caracteres — abaixo disso a requisição é rejeitada com 400. |
| limit | integer | Não | Quantidade de resultados por página. Máximo 50.Padrão: 10 |
| offset | integer | Não | Quantos resultados pular (paginação por deslocamento). Padrão: 0 |
Exemplo de requisição
curl "https://api.draftin.io/public/search?q=javascript&limit=10&offset=0" \
-H "X-API-Key: $DRAFTIN_API_KEY"async function buscar(termo) {
if (termo.trim().length < 3) return { data: [], meta: null };
const url = new URL("/public/search", "https://api.draftin.io");
url.searchParams.set("q", termo);
url.searchParams.set("limit", "10");
const res = await fetch(url, {
headers: { "X-API-Key": process.env.DRAFTIN_API_KEY },
});
const { data } = await res.json(); // desembrulha o envelope
return data; // { data: [...resultados], meta: { q, limit, offset, count } }
}interface SearchResultItem {
id: string;
title: string;
subtitle: string | null;
slug: string;
coverUrl: string | null;
publishedAt: string | null;
}
interface SearchResponse {
data: SearchResultItem[];
meta: { q: string; limit: number; offset: number; count: number };
}
async function buscar(q: string, limit = 10, offset = 0): Promise<SearchResponse> {
const url = new URL("/public/search", "https://api.draftin.io");
url.searchParams.set("q", q);
url.searchParams.set("limit", String(limit));
url.searchParams.set("offset", String(offset));
const res = await fetch(url, {
headers: { "X-API-Key": process.env.DRAFTIN_API_KEY! },
});
if (res.status === 400) throw new Error("Informe ao menos 3 caracteres.");
if (!res.ok) throw new Error(`DraftIn API: ${res.status}`);
const { data } = (await res.json()) as { data: SearchResponse };
return data;
}// Busca com debounce simples para um campo de pesquisa server-side
const BASE = "https://api.draftin.io";
async function buscar(q) {
const url = new URL("/public/search", BASE);
url.searchParams.set("q", q);
const res = await fetch(url, {
headers: { "X-API-Key": process.env.DRAFTIN_API_KEY },
});
const { data: busca } = await res.json(); // envelope → SearchResponse
console.log(`${busca.meta.count} resultados para "${busca.meta.q}"`);
return busca.data;
}
await buscar("javascript");Exemplo de resposta
{
"success": true,
"data": {
"data": [
{
"id": "clxxx101",
"title": "Introdução ao JavaScript",
"subtitle": "Do zero ao primeiro script",
"slug": "introducao-ao-javascript",
"coverUrl": "https://cdn.exemplo.com/capa.jpg",
"publishedAt": "2026-06-01T12:00:00.000Z"
}
],
"meta": { "q": "javascript", "limit": 10, "offset": 0, "count": 1 }
}
}Campos de data.data[] (SearchResultItem)
idstring
ID do post.
titlestring
Título do post.
subtitlestringnullable
Subtítulo, quando houver.
slugstring
Slug para montar o link do resultado.
coverUrlstringnullable
URL da imagem de capa, quando houver.
publishedAtstring · date-timenullable
Data/hora de publicação (ISO 8601, UTC).
Campos de data.meta
qstring
O termo de busca processado.
limitinteger
Limite aplicado nesta página.
offsetinteger
Deslocamento aplicado nesta página.
countinteger
Quantidade de itens retornados em
data nesta página.Erro de validação
Sem q ou com menos de 3 caracteres, a API responde 400:
{
"success": false,
"error": {
"message": "Erro de validação",
"code": "VALIDATION_ERROR",
"type": "field_validation",
"statusCode": 400,
"retryable": false,
"details": {
"fields": [
{ "field": "q", "message": "Campo deve ter pelo menos 3 caracteres", "code": "too_small" }
]
},
"requestId": "req_5c26469a-1234-4c8b-9e21-370450bbda3a",
"docs": "https://docs.draftin.io/errors/VALIDATION_ERROR"
}
}Respostas possíveis
| Status | Significado |
|---|---|
| 200 OK | Resultados da busca (data: objeto SearchResponse). |
| 400 Bad Request | Parâmetro q ausente ou com menos de 3 caracteres (error.code: VALIDATION_ERROR). |
| 401 Unauthorized | Chave de API inválida ou ausente. |
| 500 Internal Server Error | Erro interno; repita com backoff. |
Boas práticas
- Valide no cliente antes de chamar. Só dispare a busca a partir
de 3 caracteres — evita
400desnecessário. - Use debounce em campos de digitação para reduzir chamadas durante o typing.
- Pagine com
limit/offset(limite máximo 50) e usedata.meta.countpara saber quando parar. - Faça a busca no servidor para não expor a chave no front-end.
Casos de uso comuns
- Barra de pesquisa com resultados instantâneos (após 3 caracteres + debounce).
- Página "/buscar?q=…" com paginação e contagem por página.
- Pré-visualização rica de resultados usando
coverUrlesubtitle.