CommunityProgramación y desarrollogithub.com

sk-api

Diseñar y modificar contratos de API (REST, gRPC, protobuf, eventos) para que los llamadores existentes sigan funcionando, cubriendo la forma de recursos y métodos, modelos de error, paginación, versionado y el orden de despliegue que requiere un cambio incompatible. Úsalo al añadir o modificar un endpoint, mensaje o evento, o al evaluar si un cambio propuesto rompe a un consumidor.

¿Qué es sk-api?

Esta skill te guía en el diseño y modificación de contratos de API (REST, gRPC, protobuf, eventos) garantizando que los consumidores existentes no se vean afectados. Es fundamental al añadir o alterar endpoints, mensajes o eventos, y al evaluar si un cambio propuesto es incompatible. La skill explica qué constituye un cambio que rompe a un llamador (eliminar o renombrar campos, hacer obligatorio un campo opcional, cambiar tipos o significados) y cómo evitarlo mediante estrategias como "añadir antes de eliminar" y versionado mínimo. También cubre el orden de despliegue seguro en sistemas con código generado y proxies, y la verificación con tests de contrato. Se aplica a cualquier plataforma de API y es independiente del lenguaje de programación.

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

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Contratos de API

Un contrato es una promesa a un código que no controlas y no puedes arreglar. Eso es lo que diferencia los cambios de API de la refactorización interna: el coste de equivocarse lo paga otro, en un momento que tú no eliges.

Diseño

Nombra los recursos como sustantivos y deja que el método lleve el verbo. Modela la cosa, no la pantalla que actualmente la muestra — una carga útil moldeada alrededor de la interfaz de usuario de hoy se vuelve incorrecta en el próximo rediseño.

Sé deliberado sobre lo que expones. Cada campo que devuelves es un campo que debes seguir devolviendo. Los identificadores internos, las versiones de fila y los detalles de implementación filtran tu esquema en el código del llamador y lo congelan allí.

Haz que las operaciones sean idempotentes cuando el llamador pueda reintentar, que es cualquier operación accesible a través de una red. Dale al llamador una clave de idempotencia para cualquier cosa que cree o cobre, para que un reintento tras un tiempo de espera no pueda duplicarla.

Devuelve un modelo de error consistente: un código estable legible por máquina, un mensaje legible por humanos y el campo al que se refiere un fallo de validación. Los llamadores bifurcan según el código, por lo que forma parte del contrato — cambiar un código es un cambio incompatible aunque la forma no cambie.

Pagina cada lista desde la primera versión. Un endpoint que lo devuelve todo funciona hasta que la tabla crece y luego falla para el cliente con más datos. Prefiere un cursor sobre un desplazamiento cuando se insertan filas de forma concurrente.

Qué rompe a un llamador

Cambios incompatibles, independientemente de lo que permita el lenguaje del esquema:

  • Eliminar o renombrar un campo, un endpoint, un método o un valor de enumeración.
  • Hacer obligatorio un campo de solicitud opcional, o restringir lo que acepta un campo.
  • Cambiar un tipo, incluyendo de entero a cadena y de un valor único a una lista.
  • Cambiar el significado de un campo existente mientras se mantienen su nombre y tipo — el peor tipo, porque nada falla ruidosamente y los datos están silenciosamente incorrectos.
  • Añadir un nuevo campo obligatorio a una solicitud.
  • Cambiar un código de error, o un estado HTTP, para una condición existente.
  • Restringir un valor predeterminado, o cambiar lo que sucede cuando se omite un campo.

Cambios seguros: añadir un campo opcional de solicitud, añadir un campo de respuesta, añadir un nuevo endpoint o método, añadir un valor de enumeración solo si cada consumidor ya tolera valores desconocidos — verifica eso en lugar de asumirlo.

En protobuf, nunca reutilices o renumeres una etiqueta de campo, y reserva la etiqueta y el nombre cuando elimines un campo. Una etiqueta reutilizada decodifica datos antiguos en el nuevo campo y los corrompe silenciosamente.

Cambiar un contrato de forma segura

Añade antes de eliminar y deja que ambos funcionen durante al menos una versión:

  1. Añade el nuevo campo o método junto al antiguo.
  2. Escribe ambos, lee el nuevo con una reutilización al antiguo.
  3. Migra a los consumidores y confirma que cada uno se ha movido.
  4. Elimina la ruta antigua en una versión posterior.

Versiona cuando el recurso cambie genuinamente de significado, no por cada adición. Una versión por cambio multiplica la superficie que debes mantener viva.

Orden de despliegue

El código generado y los servidores se despliegan por separado, y el espacio entre ellos es donde viven las interrupciones. Despliega primero el lado que tolera ambas formas: consumidores que aceptan el nuevo campo antes de que los productores lo emitan, productores que aceptan la nueva solicitud antes de que los llamadores la envíen.

Cuando un esquema se comparte a través de una puerta de enlace, un proxy o clientes generados, cada componente en la ruta necesita ser regenerado y redeplomado. Un campo añadido al servicio pero no a la capa delante de él desaparece antes de llegar al llamador, y las pruebas propias del servicio no lo notarán.

Verificar

Comprueba los consumidores reales antes de cambiar una forma — busca en el código de los llamadores en lugar de confiar en la documentación del contrato.

Prueba el contrato en sí mismo: una prueba que afirma la forma serializada detecta un cambio de nombre accidental que una prueba unitaria sobre el controlador omitirá por completo.

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.

Skills relacionados