mcpField
A
api-design

api-design

github.com/s-hiraoku開発1971 回インストール4 週間前に更新
リポジトリ

api-design について

REST、GraphQL、gRPC、CLIの各インターフェースで一貫したAPIを設計・レビューするスキルです。契約、互換性、エラー文書を整えるための規約と段階的な手順を示します。

主な機能

  1. 01REST、GraphQL、gRPC、CLI APIの設計
  2. 02命名とバージョニング規約の適用
  3. 03後方互換性のある変更の計画
  4. 04レスポンスとエラー形式の定義
  5. 05ページネーションとコマンド形式の確認

活用シーン

  1. 01エンドポイントやCLIコマンドの計画
  2. 02既存API契約のレビュー
  3. 03命名とバージョニング基準の策定
  4. 04APIドキュメントやOpenAPI仕様の準備

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/s-hiraoku/synapse-a2a --skill api-design

インストール後、Claude Code で/api-designを入力して読み込まれたか確認します。

詳細

API 設計

REST、GraphQL、gRPC、CLI の各インターフェースにわたって、一貫性があり、十分に文書化された API を設計します。

使用する場面

  • 新しい API エンドポイントやコマンドを設計するとき
  • 既存の API 契約の一貫性をレビューするとき
  • API の命名規則やバージョニング規則を定めるとき
  • 後方互換性のある API の変更を計画するとき
  • API ドキュメントや OpenAPI 仕様を生成するとき

原則

  1. 一貫性 - どこでも同じパターンを使います（命名、エラー形式、ページネーション）
  2. 見つけやすさ - 開発者がドキュメントを読まなくても、適切なエンドポイントやフラグを推測できるようにします
  3. 後方互換性 - 追加は安全ですが、削除や名前の変更にはバージョニングが必要です
  4. 最小限の公開範囲 - 利用者が必要とするものだけを公開し、内部の詳細は内部にとどめます
  5. 自己説明的なエラー - エラーレスポンスには、何が問題だったのか、どう修正すればよいのかを呼び出し元に伝えます

REST API チェックリスト

命名
  • リソースには複数形の名詞を使います：/users、/tasks
  • 複数の語からなるパスにはケバブケースを使います：/user-settings
  • 所有関係を表す場合はネストします：/users/{id}/tasks
  • CRUD に当てはまらない操作にのみ動詞を使います：/tasks/{id}/approve
HTTP メソッド
メソッド目的冪等性
GET読み取りあり
POST作成／操作なし
PUT全体置換あり
PATCH部分更新あり
DELETE削除あり
レスポンス形式
{
  "data": { ... },
  "meta": { "page": 1, "total": 42 }
}

エラー形式：

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [
      { "field": "email", "reason": "required" }
    ]
  }
}
ステータスコード
コード用途
200成功（本文あり）
201作成済み
204成功（本文なし）
400クライアントエラー（バリデーション）
401認証されていない
403認可されていない
404見つからない
409競合（重複、状態の不一致）
422処理できない（意味的に無効）
500サーバーエラー
ページネーション

大規模なデータセットにはカーソルベースを使い、単純なケースにはオフセットベースを使います：

GET /tasks?cursor=abc123&limit=20
GET /tasks?page=2&per_page=20
バージョニング
  • URL プレフィックスを優先します：/v1/tasks、/v2/tasks
  • URL によるバージョニングが現実的でない場合に限り、ヘッダーベースを使います

CLI API チェックリスト

コマンド構成
<tool> <noun> <verb> [args] [--flags]

例：synapse send gemini "Review code" --wait

フラグの規則
  • ロング形式：--output、--verbose
  • よく使うフラグにはショート形式：-o、-v
  • ブール値フラグ：--force、--no-color
  • 繰り返し指定可能：--attach file1 --attach file2
  • 相互排他的なグループ：--wait | --notify | --silent
出力
  • デフォルト：人が読みやすい形式
  • --json：機械可読な JSON
  • --quiet／-q：最小限の出力
  • 終了コード：0 = 成功、1 = エラー、2 = 使用方法のエラー

ワークフロー

ステップ 1：リソース／コマンドを定義する

API がサポートする必要のあるエンティティと操作を列挙します。

ステップ 2：エンドポイント／サブコマンドに対応付ける

命名規則を適用して、API の公開範囲を定めます。

ステップ 3：リクエスト／レスポンスのスキーマを定義する

必須フィールドと任意フィールド、型、バリデーションルールを指定します。

ステップ 4：エラーケースを文書化する

各エンドポイントについて、発生しうるエラーレスポンスとその意味を列挙します。

ステップ 5：一貫性を確認する

すべてのエンドポイントで、命名、エラー形式、ページネーションを相互に確認します。

コメント

Markdown 対応