api-design-principles

api-design-principles スキルの概要

api-design-principles でできること

api-design-principles スキルは、REST API と GraphQL API の設計レビューおよびドラフト作成を支援するスキルです。曖昧なプロダクト要件を整理してより筋の良い API 形状に落とし込みたいとき、実装前に既存の仕様案をレビューしたいとき、あるいはチーム内でエンドポイントやスキーマ設計の基準をそろえたいときに特に役立ちます。

向いているユーザーとチーム

次のような場合は api-design-principles の相性が良いです。

• 新しい公開 API または社内 API を設計している
• エンドポイント案やスキーマ案の整合性をレビューしたい
• REST と GraphQL のどちらの設計パターンを採るか判断したい
• コードを書く前に避けられる設計ミスを見つけたい
• チーム向けの軽量な API 設計標準を作りたい

特に、バックエンドエンジニア、テックリード、プラットフォームチーム、そして実装そのものではなく API 契約の提案を求められる AI エージェントに向いています。

このスキルを入れる価値

このスキルの価値は、目新しさよりも「設計の型」を持てることにあります。実務的な設計ガイダンス、レビュー用チェックリスト、REST の具体例、GraphQL スキーマ設計パターンが、再利用しやすいプロンプト駆動のワークフローとしてまとまっています。単なる「API を設計して」といった汎用プロンプトに比べて、api-design-principles は次の観点でより良いデフォルトをエージェントに与えられます。

• リソース名と URL 構造
• HTTP メソッドの意味づけとステータスコード
• ページネーション、フィルタリング、バージョニング
• エラーレスポンスの一貫性
• GraphQL におけるスキーマ構成、nullability、input モデリング

できないこと

これは API gateway でも code generator でも、包括的な governance framework でもありません。設計品質やレビューの網羅性は高められますが、認可、業務ドメイン固有の制約、コンプライアンス、運用時の要件については別途自前のルールが必要です。実装の足場まで欲しい場合は同梱の FastAPI テンプレートが REST に限って参考になりますが、強みはあくまで end-to-end の開発支援より設計原則の整理にあります。

api-design-principles スキルの使い方

api-design-principles スキルをインストールする

wshobson/agents リポジトリからスキルをインストールします。

npx skills add https://github.com/wshobson/agents --skill api-design-principles

エージェント環境がスキル検出に対応しているなら、業務ロジックの実装ではなく、API の形状設計、契約レビュー、設計パラダイムの選定が主題のタスクで api-design-principles を呼び出してください。

最初に読むべきファイル

最短で使い始めるなら、次の順で読むのがおすすめです。

1. スコープと組み込みワークフローを把握するための SKILL.md
2. レビュー基準を確認する assets/api-design-checklist.md
3. 具体的な REST 規約を見る references/rest-best-practices.md
4. スキーマ設計パターンを確認する references/graphql-schema-design.md
5. REST 実装例も欲しい場合の assets/rest-api-template.py

この順番が重要なのは、実際のレビュー作業で最も密度が高く使いやすい成果物がチェックリストであり、reference 群はエージェントが出力に再利用できる具体例の供給源になるからです。

api-design-principles が必要とする中核入力を把握する

api-design-principles skill は、次の情報を与えると精度が上がります。

• ドメインオブジェクト: users, orders, invoices, projects
• 主なユーザー操作: create, list, update, search, approve
• クライアント種別: public third-party, internal web app, mobile, partner integration
• API スタイルの制約: REST, GraphQL, または “help me choose”
• 運用要件: pagination, filtering, versioning, rate limits, webhooks, real-time
• 互換性制約: existing endpoints, legacy payloads, migration limits

これらがないと、エージェントは見た目だけ整った汎用的な endpoint や浅い schema を返しがちで、実際の利用パターンを取りこぼしやすくなります。

曖昧な依頼を強いプロンプトに変える

弱い依頼:

• “Design an API for tasks.”

より良い依頼:

• “Use api-design-principles to design a REST API for a task management product. Main resources: workspaces, projects, tasks, comments. Clients: web app and mobile app. Required features: pagination, filtering by status and assignee, partial updates, audit-friendly timestamps, stable error responses, and versioning. Avoid deep nesting. Return endpoint list, request and response examples, status codes, and design rationale.”

この依頼が良い理由:

• リソースが明示されている
• クライアントの文脈がある
• 必須の振る舞いが指定されている
• スキルが最適化しやすい制約が入っている

REST 設計レビューで使う

REST の検討では、次の観点を api-design-principles に評価させるのが効果的です。

• resource nouns と action verbs の使い分け
• 浅いネストと過度に深いネストの見極め
• GET, POST, PUT, PATCH, DELETE のメソッド妥当性
• ステータスコードの選び方
• filtering, sorting, search のための query parameter 設計
• pagination パターンの選定
• versioning と deprecation の方針
• error response の一貫性

実務向きのプロンプト例:

• “Run api-design-principles against this draft endpoint list and flag naming, method semantics, pagination, and error-handling issues. Rewrite only the parts that violate established conventions.”

こうすると全面的な再設計に流れず、レビューに集中した出力になりやすくなります。

GraphQL スキーマ設計で使う

GraphQL では、単なる type 一覧ではなく、スキーマ構造の判断を求めると api-design-principles の良さが出ます。たとえば次のような依頼が有効です。

• モジュール化された schema organization
• nullability の判断
• input type と payload type の設計
• query と mutation の命名
• interface と union の使い分け
• connection-style pagination
• 典型的な client query を踏まえた field 設計

強いプロンプト例:

• “Use api-design-principles to design a GraphQL schema for a B2B support platform. Include User, Ticket, and Comment types, cursor pagination, clear mutation inputs, and sensible nullability. Explain tradeoffs where fields should remain nullable.”

api-design-principles で REST と GraphQL を比較して決める

まだ方針が決まっていないなら、プロダクト前提にひもづいた比較提案を求めるのが有効です。

• クライアントごとのリクエストの多様性
• 部分的なデータ取得の必要性
• caching と CDN との相性
• チームの学習コスト
• internal developer 向けか external developer 向けか

使いやすいプロンプト例:

• “Apply api-design-principles for API Development to compare REST and GraphQL for an internal analytics platform used by web dashboards and automation scripts. Recommend one approach and include the operational tradeoffs.”

実装前のゲートとしてチェックリストを使う

同梱の assets/api-design-checklist.md は、レビューを一定品質で回したいチームにとって最も実用的な成果物です。実装前のゲートとして扱ってください。

• すべての resource と operation をレビューする
• すべての collection で pagination を確認する
• versioning の方式を明示的に決める
• error と status code の挙動を確認する
• search, sort, sparse-field に関する抜け漏れを洗い出す

ここがこのスキルの本当の判断価値が出るポイントです。実装で契約が固定化される前に、API 契約の欠陥を見つけやすくなります。

REST テンプレートは慎重に再利用する

assets/rest-api-template.py は有用な参考資料ですが、どんな環境でもそのまま本番導入できる starter だと考えないでください。たとえば次のようなパターンを確認できます。

• FastAPI の構成
• pagination と validation
• enum の使い方
• middleware の配置
• 一貫した response handling

一方で、permissive CORS や trusted host configuration など、本番運用では明らかに詰めるべき TODO も含まれています。設計判断がコードにどう写像されるかを見るための資料として使い、セキュアな既定値を備えた drop-in テンプレートとしては扱わないでください。

より良い出力のための基本ワークフロー

信頼しやすい api-design-principles usage の流れは次のとおりです。

1. プロダクトの目的と利用者を説明する
2. リソースと価値の高い操作を列挙する
3. REST か GraphQL を選ぶ、または比較させる
4. まず第一稿の契約を出させる
5. チェックリストの観点でレビューを回す
6. pagination, errors, versioning, nullability などのエッジケースを詰める
7. その後に実装へ進む

この順番にすると、命名や契約の意味づけが早い段階で安定するため、後戻りが減ります。

api-design-principles スキルの FAQ

api-design-principles は初心者にも向いている？

はい。ただし、HTTP や GraphQL の基本概念をすでに理解していることが前提です。読みやすく、例もありますが、バックエンド開発をゼロから学ぶ教材ではなく、設計判断を支えるためのスキルです。初心者が使うなら、API をゼロから丸ごと考えさせるより、既存の草案レビューに使うほうが価値を得やすいです。

api-design-principles と汎用 AI プロンプトの違いは？

汎用プロンプトでももっともらしい endpoint は出せますが、api-design-principles はレビューの枠組みがより明確です。resource modeling、method semantics、status codes、pagination、schema structure を一貫した方向に寄せやすくなります。結果として、初稿のあとに必要な手戻りが減ることが多いです。

api-design-principles が向かないケースは？

主なニーズが次の場合は、優先度は下がります。

• 多数の framework をまたぐ code generation
• REST や GraphQL 以外の protocol-specific guidance
• 組織固有の compliance requirement
• 認可設計や event-driven architecture の深い検討

こうしたケースでも api-design-principles guide の内容が補助になることはありますが、唯一の正解ソースとして扱うべきではありません。

新規設計だけでなく既存 API にも使える？

はい。むしろ既存ドラフトのレビューや legacy API の整理は、かなり相性の良い使い方です。現在の endpoint 一覧や schema の断片を渡して、設計上の問題点、後方互換性の懸念、低リスクで進められる改善案を優先度付きで出させると有効です。

このスキルは REST と GraphQL のどちらかに偏っている？

両方を扱えますが、実装面の厚みは同じではありません。REST はチェックリストとコードテンプレートで補強されている一方、GraphQL は runtime setup よりも schema pattern と設計例の支援に強みがあります。実行可能な GraphQL scaffolding まで必要なら、追加のツールが必要です。

api-design-principles スキルを改善する方法

抽象語ではなく、実際のドメインを渡す

api-design-principles の出力を最も手早く改善する方法は、実在するエンティティと業務フローを具体的に伝えることです。“Users manage projects and invoices” のほうが “build a business API” よりはるかに有効です。ドメインが具体的だと、resource boundary、nesting、mutation shape の判断が良くなります。

クライアントが最もよく行う操作を明示する

API 設計は利用実態に従うべきです。次の点をスキルに伝えてください。

• 最重要の read path
• 最も頻繁な write operation
• 重要な filter 条件
• bulk operation が必要か
• mobile の帯域制約や third-party integration が重要か

ここは出力に大きく影響します。たとえば、重い list filtering や sparse retrieval が中心なら REST 設計の形は変わりますし、非常に多様な dashboard query が中心なら GraphQL を選ぶ理由が強くなります。

ドラフトだけでなくトレードオフも求める

弱い出力の多くは、「API design を作って」とだけ頼んで理由を問わないことから生まれます。次のような依頼にすると結果が良くなります。

• “Propose two designs and compare tradeoffs.”
• “Flag any endpoint that violates REST semantics.”
• “Explain why fields are nullable or non-null in GraphQL.”
• “Show where versioning will hurt us later.”

こうすることで、見た目は整っていても壊れやすい契約を量産するのではなく、判断理由を表に出させやすくなります。

チェックリストの観点をそのまま改稿指示に使う

最初の出力が汎用的すぎるなら、セクションごとに詰めていくのが有効です。

• “Revise only resource naming and URL hierarchy.”
• “Now review status codes and error format.”
• “Now add pagination, filtering, and sorting rules.”
• “Now review versioning and deprecation.”

チェックリストのファイルが有効なのは、「もっと良くして」という曖昧な依頼ではなく、品質を点検可能な観点に分解できるからです。

よくある失敗パターンに注意する

api-design-principles install 自体はうまくできても、出力が弱くなる主な原因は次のとおりです。

• ドメイン制約が不足している
• 対象クライアントの文脈がない
• REST と GraphQL の両方を求めているのに判断目的がない
• 既存 API との互換性要件がない
• 想定する payload shape の例がない

こうした状態だと、汎用的な resource、ぎこちない nesting、曖昧な error handling、浅い schema design に流れやすくなります。

実際の制約で出力を検証する

api-design-principles for API Development の提案を採用する前に、次を確認してください。

• 自分たちの auth model でこの operation を支えられるか
• すべての箇所で stable ID と timestamp が必要か
• collection はデフォルトで paginated されているか
• error shape はプラットフォームの慣習と一致しているか
• versioning は自分たちの release process に合っているか
• nullable な GraphQL field は意図的か

このスキルは設計品質を高めますが、最終的な契約の責任はチーム側にあります。

軽量なレビュー標準にしてチーム定着を進める

一時的な価値で終わらせたくないなら、スキルをチームの実践に落とし込むのが有効です。

• API spec の pull request でチェックリストを使う
• versioning と pagination の選択理由を必須にする
• resource と mutation の命名規約を 1 つに統一して文書化する
• 新しいパターンを導入するときは reference file を 1 つ確認する

こうすると api-design-principles usage が、一部のエンジニアしか扱えない単発のプロンプトではなく、再現可能なチームの運用になります。