Communityコーディング&開発github.com

API契約

REST、gRPC、protobuf、イベントのAPI契約を設計・変更し、既存の呼び出し元が動作し続けるようにします。リソースやメソッドの形状、エラーモデル、ページネーション、バージョニング、および破壊的変更に必要なデプロイ順序をカバーします。エンドポイント、メッセージ、イベントを追加・変更するときや、提案された変更がコンシューマを壊すかどうかを判断するときに使用します。

API契約 とは?

このスキル(API契約)は、外部のコードから呼び出されるAPIの契約を設計・変更するためのガイドラインを提供します。REST、gRPC、protobuf、イベント駆動型APIを対象とし、リソース名は名詞、メソッドは動詞とする命名規則、べき等性の確保、一貫性のあるエラーモデル、最初からページネーションを実装することを推奨します。また、フィールドの削除・型変更・必須化など、呼び出し元を壊す変更(破壊的変更)を明確に定義し、既存コンシューマを保護するためには「追加してから削除する」安全な変更手順とデプロイ順序を重視します。Claude Codeなど、AIエージェントがAPI契約を変更する際に、破壊的変更を回避し、契約の整合性を保つために利用できます。

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

Installed? Explore more コーディング&開発 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

API契約 は何をしますか?

契約とは、自分が制御できず修正もできないコードに対する約束です。これこそがAPIの変更を内部リファクタリングと異なるものにしています。間違えた場合の代償は、自分の選ばないタイミングで、誰か他の人が支払うのです。

設計

リソースには名詞で名前を付け、メソッドに動詞を担わせましょう。ものをモデル化し、それを現在表示している画面をモデル化してはいけません。今日のUIに合わせて整形されたペイロードは、次の再設計で間違ったものになります。

何を公開するかは意図的に決めましょう。返すすべてのフィールドは、返し続けなければならないフィールドです。内部ID、行バージョン、実装の詳細は、スキーマを呼び出し元のコードに漏洩させ、そこに固定してしまいます。

呼び出し元がリトライする可能性のある操作はべき等にしましょう。ネットワーク経由で到達可能な操作はすべて該当します。作成や課金を行う操作には冪等性キーを提供し、タイムアウト後のリトライで二重に実行されないようにしましょう。

一貫性のあるエラーモデルを返しましょう。安定した機械可読なコード、人間可読なメッセージ、そしてバリデーションエラーが発生したフィールドを含めます。呼び出し元はコードで分岐するため、コードは契約の一部です。コードを変更することは、形状が変わらなくても破壊的変更です。

すべてのリストは最初のバージョンからページネーションしましょう。すべてを返すエンドポイントは、テーブルが大きくなるまでは動作しますが、最もデータが多い顧客に対しては失敗します。行が同時に挿入される場合は、オフセットよりもカーソルを優先しましょう。

呼び出し元を壊すもの

スキーマ言語が許可するものであっても、以下は破壊的です:

  • フィールド、エンドポイント、メソッド、またはenum値の削除または名前変更。
  • オプションのリクエストフィールドを必須にすること、またはフィールドが受け入れる値を狭めること。
  • 型の変更(整数から文字列、単一値からリストへの変更を含む)。
  • 既存フィールドの名前と型を維持しながら意味を変更すること。これは最悪の種類で、重大な失敗はなく、データが静かに間違ってしまいます。
  • リクエストに新しい必須フィールドを追加すること。
  • 既存の条件に対するエラーコードまたはHTTPステータスの変更。
  • デフォルト値の厳格化、またはフィールドが省略された場合の動作の変更。

安全:オプションのリクエストフィールドの追加、レスポンスフィールドの追加、新しいエンドポイントまたはメソッドの追加、enum値の追加(ただしすべてのコンシューマが未知の値をすでに許容している場合に限る—それを想定せずに確認すること)。

protobufでは、フィールドタグを再利用または再割り当てしてはいけません。フィールドを削除するときは、タグと名前を予約してください。再利用されたタグは、古いデータを新しいフィールドにデコードし、静かにデータを破壊します。

契約を安全に変更する

削除する前に追加し、両方を少なくとも1リリースは動作させましょう:

  1. 古いものと並べて新しいフィールドまたはメソッドを追加する。
  2. 両方を書き、新しいものを読み、古いものにフォールバックする。
  3. コンシューマを移行し、それぞれが移行したことを確認する。
  4. 後のリリースで古いパスを削除する。

リソースの意味が実際に変わる場合にのみバージョン管理を行い、すべての追加で行ってはいけません。変更ごとにバージョンを作ると、維持しなければならない表面積が増大します。

デプロイ順序

生成されたコードとサーバーは別々にデプロイされ、そのギャップに障害が潜んでいます。まず両方の形状を許容する側をロールアウトしましょう。プロデューサーが新しいフィールドを発行する前に、それを受け入れるコンシューマーを。呼び出し元が新しいリクエストを送る前に、それを受け入れるプロデューサーを。

スキーマがゲートウェイ、プロキシ、または生成されたクライアントを通じて共有される場合、パス内のすべてのコンポーネントを再生成および再デプロイする必要があります。サービスに追加されたが、その前のレイヤーには追加されなかったフィールドは、呼び出し元に届く前に消え、サービス自身のテストでは気付かれません。

検証

形状を変更する前に実際のコンシューマを確認しましょう。契約のドキュメントを信頼するのではなく、呼び出し元をgrepしてください。

契約自体をテストしましょう。シリアル化された形状をアサートするテストは、ハンドラーの単体テストでは完全に見逃される偶発的な名前変更を捕捉します。

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.

関連スキル