スキル api-design-principles

🧭

api-design-principles

Name: api-design-principles
Author: wshobson

安全 🌐 ネットワークアクセス⚙️ 外部コマンド

RESTおよびGraphQL APIを自信を持って設計する

API設計の判断はしばしば一貫性を欠き、維持が困難になります。このスキルは、明確なパターン、テンプレート、チェックリストを提供し、あなたの選択をガイドします。

対応: Claude Codex Code(CC)

🥉 72 ブロンズ

スキルZIPをダウンロード

Claudeでアップロード

設定 → 機能 → スキル → スキルをアップロードへ移動

オンにして利用開始

テストする

「api-design-principles」を使用しています。私のユーザーと注文のエンドポイントをRESTのベストプラクティスに基づいてレビューしてください。

期待される結果:

名詞の複数形を使用してください：/api/users と /api/orders
/api/createUser のようなアクションパスを POST /api/users に置き換えてください
page と page_size を使用してリストエンドポイントにページネーションを追加してください
成功したPOSTでは201 Createdを、DELETEでは204を返してください

「api-design-principles」を使用しています。ユーザー、投稿、コメントを持つブログのGraphQLスキーマをどのように構成すべきですか？

期待される結果:

適切なリレーションシップを持つUser、Post、Commentタイプを定義してください
コレクションにはRelayスタイルのカーソルページネーションを使用してください
エラーペイロードを持つミューテーションの入力タイプを作成してください
リレーションシップでN+1クエリを防ぐためにDataLoaderを追加してください

「api-design-principles」を使用しています。バリデーションエラーに対してAPIはどのようなステータスコードを返す必要がありますか？

期待される結果:

不正なリクエスト構文には400 Bad Requestを返してください
バリデーション失敗には422 Unprocessable Entityを返してください
レスポンスボディにフィールドレベルのエラーの詳細を含めてください
すべてのエンドポイントで一貫したエラー形式を使用してください

セキュリティ監査

安全

v4 • 1/17/2026

This skill contains only educational documentation, code templates, and best practices for API design. All 233 static findings are false positives: 'weak cryptographic algorithm' flags educational password hashing examples; 'backtick execution' misinterprets markdown code formatting; 'system reconnaissance' triggers on legitimate programming terms like fetch/decode; hardcoded URLs/IPs are documentation examples, not actual network calls. No executable code, network calls, or data access patterns pose security risks.

スキャンされたファイル

2,011

解析された行数

検出結果

総監査数

リスク要因

🌐 ネットワークアクセス (7)

assets/rest-api-template.py:182 references/rest-best-practices.md:132 references/rest-best-practices.md:133 references/rest-best-practices.md:134 references/rest-best-practices.md:135 references/rest-best-practices.md:324 skill-report.json:6

⚙️ 外部コマンド (134)

監査者: claude 監査履歴を表示 →

品質スコア

アーキテクチャ

保守性

コンテンツ

コミュニティ

100

セキュリティ

仕様準拠

作れるもの

新しいAPI標準を定義する

実装前にチーム向けのRESTおよびGraphQLの一貫したルールを作成します。

API仕様書をレビューする

命名、バージョン管理、エラーハンドリングの問題について仕様を監査します。

APIの使いやすさを向上させる

エンドポイントとスキーマを洗練させて、客户端の混乱と手戻りを削減します。

これらのプロンプトを試す

REST基礎レビュー

このREST APIの概要をレビューし、命名、メソッド、ステータスコードの修正をリストアップしてください。短い修正例を提示してください。

GraphQLスキーマチェック

このGraphQLスキーマをページネーション、入力タイプ、エラーパターンについて評価してください。短い例を伴って改善案を提案してください。

バージョン管理戦略

このAPIのバージョン管理アプローチを推奨し、トレードオフを説明してください。マイグレーションのチェックリストを提供してください。

設計チェックリストの実行

この仕様にAPI設計チェックリストを適用し、各失敗したアイテムの修正とともに合格または不合格を返してください。

ベストプラクティス

起動前にバージョン管理と非推奨化のルールを文書化してください
安定したエラーコードを持つ一貫したエラー形式を使用してください
明確な制限ですべてのコレクションエンドポイントにページネーションしてください

回避

読み取り専用操作にPOSTを使用する
2レベルを超える深くネストされたリソースパス
エンドポイント間で一貫しないエラーの形状を返す

よくある質問

これはClaude、Codex、Claude Codeと互換性がありますか？

はい。プラットフォームに依存しないガイダンスで、Claude、Codex、Claude Codeで動作します。

このスキルの制限は何ですか？

パターンとテンプレートを提供しますが、完全に動作するAPIサービスを生成するものではありません。

これを既存のコードベースと統合できますか？

はい。チェックリストとテンプレートを使用して、既存のエンドポイントとスキーマを整合させることができます。

機密データにアクセスしたり、保存したりしますか？

いいえ。静的なガイダンスと例のみを提供します。

私のAPI設計がカバーされていない場合はどうすればよいですか？

仕様と目標を提供し、ターゲットを絞った推奨事項を依頼してください。

一般的なAPIアドバイスとどのように比較されますか？

チェックリストとテンプレート付きの具体的なRESTおよびGraphQLパターンが含まれています。

開発者の詳細

作成者

wshobson

ライセンス

NOASSERTION

リポジトリ

https://github.com/wshobson/agents/tree/main/plugins/backend-development/skills/api-design-principles

参照

main

ファイル構成

📁 assets/

📄 api-design-checklist.md

📄 rest-api-template.py

📁 references/

📄 graphql-schema-design.md

📄 rest-best-practices.md

📄 SKILL.md