sk-api

Concevoir et modifier des contrats d'API (REST, gRPC, protobuf, événements) pour que les appelants existants continuent de fonctionner, en couvrant la forme des ressources et des méthodes, les modèles d'erreur, la pagination, le versioning et l'ordre de déploiement qu'un changement cassant nécessite. À utiliser lors de l'ajout ou de la modification d'un point de terminaison, d'un message ou d'un événement, ou pour juger si un changement proposé casse un consommateur.

Qu'est-ce que sk-api ?

Ce skill est un guide de conception et de maintenance de contrats d'API, qu'il s'agisse de REST, gRPC, protobuf ou d'événements. Il vise à éviter les ruptures de compatibilité chez les consommateurs en définissant clairement ce qui constitue un changement cassant (suppression, renommage, ajout d'un champ obligatoire en requête, changement de type ou de code d'erreur) et ce qui est sûr (ajout de champs optionnels ou de nouveaux endpoints). Il couvre la pagination, l'idempotence, la gestion des erreurs et l'ajout progressif des fonctionnalités. Il insiste sur l'ordre de déploiement : d'abord les consommateurs tolérants, puis les producteurs, et enfin mise à jour des intermédiaires. Le skill fournit des règles pratiques pour protobuf (ne pas réutiliser les tags) et propose une stratégie de migration en quatre étapes. Il recommande aussi de tester le contrat lui-même et de vérifier les appelants réels avant tout changement.

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

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Contrats d'API

Un contrat est une promesse faite à du code que vous ne contrôlez pas et que vous ne pouvez pas corriger. C'est ce qui rend les changements d'API différents d'un refactoring interne : le coût d'une erreur est payé par quelqu'un d'autre, à un moment que vous ne choisissez pas.

Conception

Nommez les ressources comme des noms et laissez la méthode porter le verbe. Modélisez la chose, pas l'écran qui l'affiche actuellement — une charge utile façonnée autour de l'interface d'aujourd'hui devient erronée lors de la prochaine refonte.

Soyez délibéré sur ce que vous exposez. Chaque champ que vous retournez est un champ que vous devez continuer à retourner. Les identifiants internes, les numéros de version de ligne et les détails d'implémentation laissent votre schéma s'infiltrer dans le code de l'appelant et le figent là.

Rendez les opérations idempotentes là où l'appelant peut réessayer, c'est-à-dire toute opération accessible via un réseau. Donnez à l'appelant une clé d'idempotence pour tout ce qui crée ou facture, afin qu'une nouvelle tentative après un délai d'attente ne puisse pas le dupliquer.

Renvoie un modèle d'erreur cohérent : un code stable lisible par machine, un message lisible par l'humain et le champ auquel se rapporte un échec de validation. Les appelants se basent sur le code, donc il fait partie du contrat — changer un code est un changement cassant même si la forme reste inchangée.

Paginer chaque liste, dès la première version. Un endpoint qui retourne tout fonctionne jusqu'à ce que la table grandisse, puis échoue pour le client avec le plus de données. Préférez un curseur à un décalage (offset) lorsque les lignes sont insérées simultanément.

Ce qui casse un appelant

Cassant, quoi que permette le langage de schéma :

  • Supprimer ou renommer un champ, un endpoint, une méthode ou une valeur d'énumération.
  • Rendre un champ de requête facultatif obligatoire, ou restreindre ce qu'un champ accepte.
  • Changer un type, y compris entier en chaîne et une valeur unique en liste.
  • Changer le sens d'un champ existant tout en conservant son nom et son type — le pire, car rien n'échoue bruyamment et les données sont silencieusement erronées.
  • Ajouter un nouveau champ obligatoire à une requête.
  • Changer un code d'erreur ou un statut HTTP pour une condition existante.
  • Resserer une valeur par défaut, ou modifier ce qui se passe lorsqu'un champ est omis.

Sûr : ajouter un champ de requête facultatif, ajouter un champ de réponse, ajouter un nouveau endpoint ou une nouvelle méthode, ajouter une valeur d'énumération uniquement si chaque consommateur tolère déjà les valeurs inconnues — vérifiez cela plutôt que de le supposer.

Dans protobuf, ne réutilisez ni ne renumérotez jamais une balise de champ, et réservez la balise et le nom lorsque vous supprimez un champ. Une balise réutilisée décode les anciennes données dans le nouveau champ et les corrompt silencieusement.

Modifier un contrat en toute sécurité

Ajoutez avant de supprimer, et laissez les deux fonctionner pendant au moins une version :

  1. Ajoutez le nouveau champ ou la nouvelle méthode à côté de l'ancien.
  2. Écrivez les deux, lisez le nouveau avec un repli sur l'ancien.
  3. Migrez les consommateurs et confirmez que chacun a bougé.
  4. Supprimez l'ancien chemin dans une version ultérieure.

Versionnez lorsque la ressource change réellement de sens, pas pour chaque ajout. Une version par changement multiplie la surface que vous devez maintenir en vie.

Ordre de déploiement

Le code généré et les serveurs sont déployés séparément, et l'écart est là où résident les pannes. Déployez d'abord le côté qui tolère les deux formes : les consommateurs qui acceptent le nouveau champ avant que les producteurs ne l'émettent, les producteurs qui acceptent la nouvelle requête avant que les appelants ne l'envoient.

Lorsqu'un schéma est partagé via une passerelle, un proxy ou des clients générés, chaque composant du chemin doit être régénéré et redéployé. Un champ ajouté au service mais pas à la couche qui le précède disparaît avant d'atteindre l'appelant, et les propres tests du service ne le remarqueront pas.

Vérifier

Vérifiez les consommateurs réels avant de modifier une forme — greppez les appelants plutôt que de vous fier à la documentation du contrat.

Testez le contrat lui-même : un test qui vérifie la forme sérialisée détecte un renommage accidentel qu'un test unitaire sur le gestionnaire manquera complètement.

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 associés