sk-api

Projetar e alterar contratos de API (REST, gRPC, protobuf, eventos) para que chamadores existentes continuem funcionando, abrangendo forma de recursos e métodos, modelos de erro, paginação, versionamento e a ordem de implantação exigida por uma alteração de quebra. Use ao adicionar ou modificar um endpoint, mensagem ou evento, ou ao julgar se uma alteração proposta quebra um consumidor.

O que é sk-api?

Esta skill, sk-api, é uma ferramenta especializada para desenvolvedores e engenheiros de software que trabalham com design e manutenção de contratos de API, incluindo REST, gRPC, protobuf e eventos. Ela fornece diretrizes e práticas recomendadas para criar e evoluir APIs de forma segura, garantindo que mudanças não quebrem os consumidores existentes. A skill abrange desde princípios fundamentais de design, como nomear recursos como substantivos e modelar a coisa real em vez da tela atual, até regras detalhadas sobre o que constitui uma alteração de quebra — como remover campos, tornar opcionais em obrigatórios, alterar tipos ou significados. Ela também oferece estratégias para mudanças seguras, como adicionar antes de remover e permitir que ambos coexistam por pelo menos um ciclo de release, além de considerar a ordem de implantação para evitar interrupções. Compatível com plataformas como Claude Code, Cursor e Codex, a skill ajuda a evitar erros comuns, como reutilizar tags de campo em protobuf ou confiar apenas na documentação do contrato, incentivando a verificação com consumidores reais e testes de serialização. Em suma, é um guia prático para manter a confiabilidade e a compatibilidade de APIs ao longo do tempo.

Funciona com~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/vanhuydotcom/sk-skills/tree/HEAD/skills/sk-api

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Contratos de API

Um contrato é uma promessa para código que você não controla e não pode corrigir. É isso que torna as mudanças de API diferentes da refatoração interna: o custo de errar é pago por outra pessoa, em um momento que você não escolhe.

Design

Nomeie recursos como substantivos e deixe que o método carregue o verbo. Modele a coisa, não a tela que atualmente a exibe — uma carga útil moldada em torno da IU de hoje se torna errada na próxima reformulação.

Seja deliberado sobre o que você expõe. Todo campo que você retorna é um campo que você deve continuar retornando. Identificadores internos, versões de linha e detalhes de implementação vazam seu esquema para o código do chamador e o congelam ali.

Torne as operações idempotentes onde o chamador pode repetir, o que é qualquer operação alcançável por uma rede. Forneça ao chamador uma chave de idempotência para qualquer coisa que crie ou cobre, para que uma repetição após um tempo limite não possa duplicá-la.

Retorne um modelo de erro consistente: um código estável legível por máquina, uma mensagem legível por humanos e o campo ao qual uma falha de validação se refere. Os chamadores se ramificam com base no código, então ele faz parte do contrato — alterar um código é uma mudança de quebra, mesmo que a forma permaneça inalterada.

Paginação em toda lista, desde a primeira versão. Um endpoint que retorna tudo funciona até que a tabela cresça e então falha para o cliente com mais dados. Prefira um cursor a um deslocamento quando linhas são inseridas simultaneamente.

O que quebra um chamador

Quebra, independentemente do que a linguagem de esquema permite:

  • Remover ou renomear um campo, um endpoint, um método ou um valor de enum.
  • Tornar um campo de solicitação opcional em obrigatório, ou restringir o que um campo aceita.
  • Alterar um tipo, incluindo de inteiro para string e de valor único para lista.
  • Alterar o significado de um campo existente enquanto mantém seu nome e tipo — o pior tipo, porque nada falha ruidosamente e os dados estão silenciosamente errados.
  • Adicionar um novo campo obrigatório a uma solicitação.
  • Alterar um código de erro ou um status HTTP para uma condição existente.
  • Apertar um padrão, ou alterar o que acontece quando um campo é omitido.

Seguro: adicionar um campo de solicitação opcional, adicionar um campo de resposta, adicionar um novo endpoint ou método, adicionar um valor de enum apenas se todo consumidor já tolerar valores desconhecidos — verifique isso em vez de presumir.

Em protobuf, nunca reutilize ou renumere uma tag de campo, e reserve a tag e o nome quando você remover um campo. Uma tag reutilizada decodifica dados antigos no novo campo e os corrompe silenciosamente.

Alterando um contrato com segurança

Adicione antes de remover, e deixe ambos funcionarem por pelo menos um release:

  1. Adicione o novo campo ou método junto com o antigo.
  2. Escreva ambos, leia o novo com um fallback para o antigo.
  3. Migre os consumidores e confirme que cada um se moveu.
  4. Remova o caminho antigo em um release posterior.

Versione quando o recurso realmente muda de significado, não para cada adição. Uma versão por mudança multiplica a superfície que você deve manter viva.

Ordem de implantação

Código gerado e servidores são implantados separadamente, e a lacuna é onde as interrupções vivem. Implemente primeiro o lado que tolera ambas as formas: consumidores que aceitam o novo campo antes de produtores emiti-lo, produtores que aceitam a nova solicitação antes de chamadores enviá-la.

Quando um esquema é compartilhado através de um gateway, um proxy ou clientes gerados, todo componente no caminho precisa ser regenerado e reimplantado. Um campo adicionado ao serviço, mas não à camada na frente dele, desaparece antes de alcançar o chamador, e os próprios testes do serviço não perceberão.

Verificar

Verifique os consumidores reais antes de alterar uma forma — faça grep nos chamadores em vez de confiar na documentação do contrato.

Teste o contrato em si: um teste que afirma a forma serializada captura uma renomeação acidental que um teste unitário no manipulador perderá completamente.

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

sk-code-review

Shows an agent how to design, debug, or review "sk code review" so the concrete output is a code change with a check. The procedure moves through Code review, Establish the diff first, What to look for, in priority order. Use it when a new assignment calls for this craft.

sk-go-service

Implement, extend or debug a handler, service or repository in a Go backend service, covering context propagation, error wrapping, transaction boundaries, tenancy scoping and table-driven tests. Use when writing or changing Go server code, adding an endpoint or gRPC method, touching a repository query, or diagnosing a panic, leak or flaky test in a Go service.

sk-python

Write and debug Python with attention to the traps that produce silent wrong behaviour — mutable defaults, late-binding closures, shallow copies, swallowed exceptions — plus typing, environment and packaging with uv or venv, and pytest structure. Use when writing a Python script, service or library, setting up a Python project, or debugging behaviour that looks impossible.

sk-react

Build and fix React and TypeScript components, covering state placement, effect dependencies, data fetching, list rendering and the re-render traps that cause stale or looping UI. Use when writing or changing a React component or hook, debugging stale data, an infinite render loop or a lost input, or reviewing frontend code.

sk-system-design

Design or evaluate a distributed system from its constraints — service boundaries, synchronous versus event-driven communication, consistency, failure behaviour and capacity — and state the trade-off each choice buys. Use when splitting or merging services, choosing between a call and an event, deciding where data lives, reviewing an architecture proposal, or answering a system design question.

Habilidades Relacionadas