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 um envelope SearchResponse com os resultados em data e os metadados em 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 },
});
return res.json();
} 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}`);
return res.json() as Promise<SearchResponse>;
} // 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, meta } = await res.json();
console.log(`${meta.count} resultados para "${meta.q}"`);
return data;
}
await buscar("javascript"); Exemplo de resposta
{
"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[] (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 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:
{
"error": "Parâmetro \"q\" obrigatório (mínimo 3 caracteres)"
} Respostas possíveis
| Status | Significado |
|---|---|
| 200 OK | Resultados da busca (envelope SearchResponse). |
| 400 Bad Request | Parâmetro q ausente ou com menos de 3 caracteres. |
| 401 Unauthorized | Chave de API inválida ou ausente. |
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 usemeta.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.