Criar chamadas `fetch` manualmente, gerenciar tokens de autenticação e analisar respostas de API para cada nova integração é o equivalente moderno a escrever código assembly para aplicativos web. As Claude Code Skills para busca de dados transformam requisições HTTP em ferramentas declarativas e reutilizáveis que entendem padrões de autenticação, paginação e validação de resposta, eliminando o código repetitivo (boilerplate) e garantindo a consistência em sua base de código.
Por Que as Skills de Rede de API São Importantes para Fluxos de Trabalho de Desenvolvimento
Todo desenvolvedor gasta horas em tarefas repetitivas de API: configurando cabeçalhos para OAuth 2.0, implementando `exponential backoff` para endpoints com limite de taxa e escrevendo `type guards` para respostas JSON imprevisíveis. Essas tarefas são propensas a erros e fortemente acopladas a serviços específicos, tornando-as difíceis de testar e manter. As Claude Code Skills abstraem essa complexidade em ferramentas versionadas e testáveis que seu assistente de IA pode invocar com linguagem natural.
A mudança é de chamadas de API imperativas para busca de dados declarativa. Em vez de escrever fetch(url, { headers: {...} }), você descreve a intenção: “Busque dados do usuário da API do GitHub usando o token do ENV e retorne resultados tipados.” A skill lida com o gerenciamento de credenciais, lógica de novas tentativas e análise de resposta, retornando dados fortemente tipados que seu aplicativo pode consumir imediatamente.
Quer uma plataforma integrada e completa para sua Equipe de Desenvolvedores trabalhar com máxima produtividade?
Apidog atende a todas as suas demandas e substitui o Postman por um preço muito mais acessível!
botão
Configurando a Skill de Busca de Dados no Claude Code
Passo 1: Instale o Claude Code e Configure o MCP
Se você ainda não instalou o CLI do Claude Code:
npm install -g @anthropic-ai/claude-code
claude --version # Should show >= 2.0.70
Crie o diretório e o arquivo de configuração do MCP:
# macOS/Linux
mkdir -p ~/.config/claude-code
touch ~/.config/claude-code/config.json
# Windows
mkdir %APPDATA%\claude-code
echo {} > %APPDATA%\claude-code\config.json
Passo 2: Clone e Compile a Skill de Busca de Dados
A skill oficial de busca de dados fornece padrões para requisições REST, GraphQL e HTTP genéricas.
git clone https://github.com/anthropics/skills.git
cd skills/skills/data-fetching
npm install
npm run build
Isso compila os manipuladores TypeScript para dist/index.js.
Passo 3: Configure o MCP para Carregar a Skill
Edite ~/.config/claude-code/config.json:
{
"mcpServers": {
"data-fetching": {
"command": "node",
"args": ["/absolute/path/to/skills/data-fetching/dist/index.js"],
"env": {
"DEFAULT_TIMEOUT": "30000",
"MAX_RETRIES": "3",
"RATE_LIMIT_PER_MINUTE": "60",
"CREDENTIALS_STORE": "~/.claude-credentials.json"
}
}
}
}
Crítico:
- Use caminhos absolutos para
args - Configure as variáveis de ambiente:
DEFAULT_TIMEOUT: Tempo limite da requisição em milissegundosMAX_RETRIES: Número de tentativas para erros 5xxRATE_LIMIT_PER_MINUTE: Limite de taxa de requisiçõesCREDENTIALS_STORE: Caminho para o arquivo de credenciais criptografadas
Passo 4: Configure o Armazenamento de Credenciais
Crie o arquivo de credenciais para evitar tokens hardcoded:
# Crie o armazenamento de credenciais criptografadas
mkdir -p ~/.claude
echo '{}' > ~/.claude/credentials.json
chmod 600 ~/.claude/credentials.json
Adicione seus tokens de API:
{
"github": {
"token": "ghp_your_github_token_here",
"baseUrl": "https://api.github.com"
},
"slack": {
"token": "xoxb-your-slack-token",
"baseUrl": "https://slack.com/api"
},
"custom-api": {
"token": "Bearer your-jwt-token",
"baseUrl": "https://api.yourcompany.com",
"headers": {
"X-API-Version": "v2"
}
}
}
A skill lê este arquivo na inicialização e injeta as credenciais nas requisições.
Passo 5: Verifique a Instalação
claude
Uma vez carregado, execute:
/list-tools
Você deverá ver:
Available tools:
- data-fetching:rest-get
- data-fetching:rest-post
- data-fetching:rest-put
- data-fetching:rest-delete
- data-fetching:graphql-query
- data-fetching:graphql-mutation
- data-fetching:raw-http
Padrões Essenciais de Requisições de API
1. Requisições GET RESTful
Ferramenta: data-fetching:rest-get
Caso de uso: Busca dados de endpoints REST com autenticação, paginação e cache
Parâmetros:
service: Chave correspondente ao armazenamento de credenciais (github, slack, custom-api)endpoint: Caminho da API (ex:/users,/repos/owner/name)params: Objeto de parâmetros de consultacache: TTL em segundos (opcional)transform: Expressão JMESPath para transformação da resposta
Exemplo: Buscar repositórios de usuários do GitHub
Use rest-get para buscar os repositórios do usuário "anthropics" da API do GitHub, incluindo paginação para 100 itens por página, e retorne apenas nome, descrição e stargazers_count.
Execução gerada:
// Handler executes:
const response = await fetch('https://api.github.com/users/anthropics/repos', {
headers: {
'Authorization': 'token ghp_your_github_token_here',
'Accept': 'application/vnd.github.v3+json'
},
params: {
per_page: 100,
page: 1
}
});
// Transform with JMESPath
const transformed = jmespath.search(response, '[*].{name: name, description: description, stars: stargazers_count}');
return transformed;
Uso do Claude Code:
claude --skill data-fetching \
--tool rest-get \
--params '{"service": "github", "endpoint": "/users/anthropics/repos", "params": {"per_page": 100}, "transform": "[*].{name: name, description: description, stars: stargazers_count}"}'
2. Requisições POST/PUT/DELETE
Ferramenta: data-fetching:rest-post / rest-put / rest-delete
Caso de uso: Criar, atualizar ou deletar recursos
Parâmetros:
service: Chave do armazenamento de credenciaisendpoint: Caminho da APIbody: Corpo da requisição (objeto ou string JSON)headers: Cabeçalhos adicionaisidempotencyKey: Para segurança de novas tentativas
Exemplo: Criar uma issue no GitHub
Use rest-post para criar uma issue no repositório anthorpics/claude com o título "Feature Request: MCP Tool Caching", corpo contendo a descrição, e labels ["enhancement", "mcp"].
Execução:
await fetch('https://api.github.com/repos/anthropics/claude/issues', {
method: 'POST',
headers: {
'Authorization': 'token ghp_...',
'Content-Type': 'application/json'
},
body: JSON.stringify({
title: "Feature Request: MCP Tool Caching",
body: "Description of the feature...",
labels: ["enhancement", "mcp"]
})
});
3. Consultas GraphQL
Ferramenta: data-fetching:graphql-query
Caso de uso: Busca complexa de dados com relacionamentos aninhados
Parâmetros:
service: Chave do armazenamento de credenciaisquery: String da consulta GraphQLvariables: Objeto de variáveis da consultaoperationName: Operação nomeada
Exemplo: Buscar issues do repositório com comentários
Use graphql-query para buscar as 10 issues abertas mais recentes do repositório anthorpics/skills, incluindo título, autor, contagem de comentários e labels.
query RecentIssues($owner: String!, $repo: String!, $limit: Int!) {
repository(owner: $owner, name: $repo) {
issues(first: $limit, states: [OPEN], orderBy: {field: CREATED_AT, direction: DESC}) {
nodes {
title
author { login }
comments { totalCount }
labels(first: 5) { nodes { name } }
}
}
}
}
Parâmetros:
{
"service": "github",
"query": "query RecentIssues($owner: String!, $repo: String!, $limit: Int!) { ... }",
"variables": {
"owner": "anthropics",
"repo": "skills",
"limit": 10
}
}
4. Requisições HTTP Puras
Ferramenta: data-fetching:raw-http
Caso de uso: Casos de uso específicos não cobertos pelas ferramentas REST/GraphQL
Parâmetros:
url: URL completamethod: Método HTTPheaders: Objeto de cabeçalhosbody: Corpo da requisiçãotimeout: Sobrescrever o tempo limite padrão
Exemplo: Entrega de webhook com cabeçalhos personalizados
Use raw-http para POSTar para https://hooks.slack.com/services/YOUR/WEBHOOK/URL com um payload JSON contendo {text: "Deployment complete"}, e cabeçalho customizado X-Event: deployment-success.
Cenários Avançados de Rede
Tratamento de Paginação
A skill detecta automaticamente padrões de paginação:
// GitHub Link header parsing
const linkHeader = response.headers.get('Link');
if (linkHeader) {
const nextUrl = parseLinkHeader(linkHeader).next;
if (nextUrl && currentPage < maxPages) {
return {
data: currentData,
nextPage: currentPage + 1,
hasMore: true
};
}
}
Solicitar todas as páginas:
Use rest-get para buscar todos os repositórios do usuário "anthropics", tratando a paginação automaticamente até que não haja mais páginas.
A skill retorna um array plano de todos os resultados.
Limite de Taxa e Lógica de Nova Tentativa
Configure o comportamento de novas tentativas por requisição:
{
"service": "github",
"endpoint": "/rate_limit",
"maxRetries": 5,
"retryDelay": "exponential",
"retryOn": [429, 500, 502, 503, 504]
}
A skill implementa `exponential backoff` com `jitter`:
const delay = Math.min(
(2 ** attempt) * 1000 + Math.random() * 1000,
30000
);
await new Promise(resolve => setTimeout(resolve, delay));
Gerenciamento de Requisições Concorrentes
Agrupe várias chamadas de API de forma eficiente:
Use rest-get para buscar detalhes dos repositórios: ["claude", "skills", "anthropic-sdk"], executando requisições concorrentemente com um máximo de 3 conexões paralelas.
A skill usa `p-limit` para controlar a concorrência:
import pLimit from 'p-limit';
const limit = pLimit(3); // Max 3 concurrent
const results = await Promise.all(
repos.map(repo =>
limit(() => fetchRepoDetails(repo))
)
);
Interceptação e Mocking de Requisições
Para testes, intercepte requisições sem acessar APIs reais:
// Na configuração da skill
"env": {
"MOCK_MODE": "true",
"MOCK_FIXTURES_DIR": "./test/fixtures"
}
Agora as requisições retornam dados `mockados` de arquivos JSON:
// test/fixtures/github/repos/anthropics.json
[
{"name": "claude", "description": "AI assistant", "stars": 5000}
]
Aplicação Prática: Construindo um Painel do GitHub
Passo 1: Buscar Dados do Repositório
Use rest-get para buscar todos os repositórios do GitHub para a organização "anthropics", incluindo descrição completa, contagem de estrelas, contagem de forks e contagem de issues abertas. Armazene em cache os resultados por 5 minutos.
Passo 2: Enriquecer com Dados do Contribuinte
Para cada repositório, busque os principais contribuidores:
Use rest-get para buscar estatísticas de contribuidores para o repositório "anthropics/claude", limitando aos 10 principais contribuidores, e extraia o login e a contagem de contribuições.
Passo 3: Gerar Estatísticas de Resumo
Combine dados no Claude Code:
const repos = await fetchAllRepos('anthropics');
const enrichedRepos = await Promise.all(
repos.map(async (repo) => {
const contributors = await fetchTopContributors('anthropics', repo.name);
return { ...repo, topContributors: contributors };
})
);
return {
totalStars: enrichedRepos.reduce((sum, r) => sum + r.stars, 0),
totalForks: enrichedRepos.reduce((sum, r) => sum + r.forks, 0),
repositories: enrichedRepos
};
Passo 4: Publicar Painel
Use rest-post para criar um site GitHub Pages com os dados do painel usando a API do GitHub para commitar na branch gh-pages.
Tratamento de Erros e Resiliência
A skill categoriza erros para um tratamento adequado:
// 4xx errors: Client errors
if (response.status >= 400 && response.status < 500) {
throw new SkillError('client_error', `Invalid request: ${response.status}`, {
statusCode: response.status,
details: await response.text()
});
}
// 5xx errors: Server errors (retry eligible)
if (response.status >= 500) {
throw new SkillError('server_error', `Server error: ${response.status}`, {
retryable: true,
statusCode: response.status
});
}
// Network errors: Connection failures
if (error.code === 'ECONNREFUSED' || error.code === 'ETIMEDOUT') {
throw new SkillError('network_error', 'Network unreachable', {
retryable: true,
originalError: error.message
});
}
O Claude Code recebe erros estruturados e pode decidir tentar novamente, abortar ou solicitar intervenção do usuário.
Conclusão
As Claude Code Skills para rede de API transformam requisições HTTP ad-hoc em ferramentas de busca de dados confiáveis, com segurança de tipo e observáveis. Ao centralizar o gerenciamento de credenciais, implementar novas tentativas inteligentes e fornecer tratamento de erros estruturado, você elimina as fontes mais comuns de bugs na integração de APIs. Comece com as quatro ferramentas principais—rest-get, rest-post, graphql-query e raw-http—e então estenda-as para seus casos de uso específicos. O investimento na configuração de skills traz dividendos imediatos em consistência de código e velocidade de desenvolvimento.
Quando suas skills de busca de dados interagirem com APIs internas, valide esses endpoints com o Apidog para garantir que suas integrações baseadas em IA consumam contratos confiáveis.
botão