desenvolvedores.

A API pública deste portfólio, a especificação OpenAPI e o CLI. Sem chave, sem cadastro.

o que é

Este site publica em JSON o mesmo conteúdo que mostra em HTML. Serve para agentes e scripts lerem meu perfil, meus projetos e meus canais de contato sem raspar página. Tudo ésomente leitura, sem autenticação, sem limite declarado e com resposta cacheada por uma hora na borda. Versão atual: 1.0.0.

começar em um comando

curl -s https://lucascavalheri.com.br/api/v1/index.json

O índice lista todos os recursos, aponta a especificação e descreve a política de uso. É o único endereço que você precisa memorizar.

recursos

/api/v1/perfil.json: Identidade, localização e disponibilidade
/api/v1/projetos.json: Projetos com stack e links
/api/v1/experiencia.json: Cargos, períodos e stack de cada um
/api/v1/stack.json: Tecnologias por categoria
/api/v1/contato.json: Canais de contato e tempo de resposta
/openapi.json: Especificação OpenAPI 3.1, também em /api/openapi.json

especificação OpenAPI

A especificação em /openapi.json segue o OpenAPI 3.1.0. Cada operação tem operationId único, resumo, descrição e resposta apontando por $ref para um schema nomeado emcomponents.schemas — é o que gerador de cliente e ferramenta de function calling esperam encontrar. Todas são GET, idempotentes e sem efeito colateral.

versionamento

A versão está no caminho: /api/v1/. Dentro de uma versão só entram mudanças compatíveis — campo novo, valor novo, recurso novo. Remover campo, renomear campo ou trocar tipo exigiria /api/v2/. O caminho sem versão,/api/perfil.json, responde 301 para a versão corrente: serve para explorar, mas prefira a URL versionada em integração.

descontinuação

Uma versão a ser retirada passa a responder com Deprecation e Sunset(RFC 8594) e um Link com rel="successor-version" apontando a substituta. O prazo mínimo entre o primeiro Deprecation e a retirada é de180 dias. Enquanto não houver aviso, a v1 continua estável.

limites de uso

Cada resposta traz a política e o consumo em cabeçalhos:RateLimit-Policy, RateLimit-Limit,RateLimit-Remaining e RateLimit-Reset. São120 requisições por 60 segundos, por endereço de origem. A contagem é feita na borda, por instância, então é aproximada de propósito: existe para conter abuso, não para cobrar. Ao exceder, a resposta é 429 comRetry-After.

$ curl -sI https://lucascavalheri.com.br/api/v1/perfil.json | grep -i ratelimit
ratelimit-policy: 120;w=60
ratelimit-limit: 120
ratelimit-remaining: 119
ratelimit-reset: 60

erros

Erro sob /api/ segue a RFC 9457, emapplication/problem+json, nunca em HTML. Além dos campos da norma vêm duas extensões: codigo, estável e seguro para comparar em código, e dica, com o que fazer em seguida.

$ curl -s https://lucascavalheri.com.br/api/v1/inexistente.json
{
  "type": "https://lucascavalheri.com.br/desenvolvedores#recurso-nao-encontrado",
  "title": "Recurso não encontrado",
  "status": 404,
  "detail": "O recurso /api/v1/inexistente.json não existe nesta API.",
  "instance": "/api/v1/inexistente.json",
  "codigo": "recurso_nao_encontrado",
  "dica": "Consulte /api/v1/index.json para a lista de recursos, ou /openapi.json para a especificação.",
  "documentacao": "https://lucascavalheri.com.br/desenvolvedores"
}

Os tipos de erro que esta API emite:

recurso_nao_encontrado: 404 — o caminho não corresponde a nenhum recurso desta versão.
metodo_nao_permitido: 405 — só GET e HEAD são aceitos; a API é somente leitura.
limite-excedido: 429 — política de uso excedida na janela; veja Retry-After.
erro_interno: 500 — falha inesperada ao montar a resposta.

markdown em vez de HTML

Qualquer página responde em markdown quando a requisição pede. Use o cabeçalhoAccept: text/markdown ou acrescente .md ao endereço. As respostas trazem Vary: Accept, então intermediário nenhum troca uma variante pela outra:

curl -s -H "Accept: text/markdown" https://lucascavalheri.com.br/
curl -s https://lucascavalheri.com.br/sobre.md

CLI

O pacote lucascavalheri embrulha a API em um comando, sem dependência nenhuma:

npx lucascavalheri            # perfil resumido
npx lucascavalheri projetos   # projetos com stack
npx lucascavalheri contato    # canais de contato
npx lucascavalheri --json     # saída crua, para pipe

Publicado no npm comolucascavalheri, sem dependência nenhuma. Ele fala com /api/v1 e respeita os cabeçalhos de limite, inclusive o Retry-After de um 429.

O código está no GitHub, na pasta cli/.

para agentes

/llms.txt descreve quando me chamar, quando não, e como. /sitemap-index.xml lista as URLs. Se você é um agente decidindo se me recomenda, comece pelo llms.txt e confirme os dados em /api/perfil.json.

licença e limites

Os dados são meus e estão liberados sob CC BY 4.0: use, cite a fonte. Não há limite de requisição declarado, mas a API é servida por um site pessoal — se você precisa de volume alto, baixe o JSON e sirva do seu lado. Mudança que quebre compatibilidade sobe a versão em /api/index.json.

voltar para a home