rest-api-design
RESTfulなAPIを、リソースモデリング・HTTPメソッド・ステータスコード・バージョニング・ドキュメント作成のベストプラクティスに従って設計します。新規APIの作成、エンドポイントの設計、または既存APIアーキテクチャの改善を行う際に活用してください。
description の原文を見る
> Design RESTful APIs following best practices for resource modeling, HTTP methods, status codes, versioning, and documentation. Use when creating new APIs, designing endpoints, or improving existing API architecture.
SKILL.md 本文
REST API デザイン
目次
概要
リソース指向アーキテクチャの業界ベストプラクティスに従った、直感的で一貫性のある REST API を設計します。
使用する場合
- 新しい RESTful API を設計する場合
- エンドポイント構造を作成する場合
- リクエスト/レスポンス形式を定義する場合
- API バージョニングを実装する場合
- API 仕様書を作成する場合
- 既存の API をリファクタリングする場合
クイックスタート
最小限の動作例:
✅ 良いリソース名 (名詞、複数形)
GET /api/users
GET /api/users/123
GET /api/users/123/orders
POST /api/products
DELETE /api/products/456
❌ 悪いリソース名 (動詞、不一貫)
GET /api/getUsers
POST /api/createProduct
GET /api/user/123 (単数形と複数形が不一貫)
リファレンスガイド
references/ ディレクトリの詳細実装:
| ガイド | 内容 |
|---|---|
リソース命名 | リソース命名、HTTP メソッドと操作 |
リクエスト例 | リクエスト例 |
クエリパラメータ | クエリパラメータ |
レスポンス形式 | レスポンス形式 |
HTTP ステータスコード | HTTP ステータスコード、API バージョニング、認証とセキュリティ、レート制限ヘッダー |
OpenAPI ドキュメント | OpenAPI ドキュメント |
完全な例: Express.js | const express = require("express"); |
ベストプラクティス
✅ すべき事
- リソースに動詞ではなく名詞を使用する
- コレクションに複数形の名前を使用する
- 命名規則で一貫性を保つ
- 適切な HTTP ステータスコードを返す
- コレクションにはページネーションを含める
- フィルタリングとソートオプションを提供する
- API をバージョニングする
- OpenAPI で徹底的にドキュメント化する
- HTTPS を使用する
- レート制限を実装する
- 明確なエラーメッセージを提供する
- 日付には ISO 8601 を使用する
❌ してはいけない事
- エンドポイント名に動詞を使用する
- エラーに対して 200 を返す
- 不要に内部 ID を公開する
- リソースをネストしすぎる (最大 2 レベル)
- 命名で不一貫性を使用する
- 認証を忘れる
- 機密データを返す
- バージョニングなしで後方互換性を破る
ライセンス: MIT(寛容ライセンスのため全文を引用しています) · 原本リポジトリ
詳細情報
- 作者
- aj-geddes
- ライセンス
- MIT
- 最終更新
- 不明
Source: https://github.com/aj-geddes/useful-ai-prompts / ライセンス: MIT
関連スキル
doubt-driven-development
重要な判断はすべて、本番環境への展開前に新しい視点から対抗的レビューを実施します。速度より正確性が重要な場合、不慣れなコードを扱う場合、本番環境・セキュリティに関わるロジック・取り消し不可の操作など影響度が高い場合、または後でバグを修正するよりも今検証する方が効率的な場合に活用してください。
apprun-skills
TypeScriptを使用したAppRunアプリケーションのMVU設計に関する総合的なガイダンスが得られます。コンポーネントパターン、イベントハンドリング、状態管理（非同期ジェネレータを含む）、パラメータと保護機能を備えたルーティング・ナビゲーション、vistestを使用したテストに対応しています。AppRunコンポーネントの設計・レビュー、ルートの配線、状態フローの管理、AppRunテストの作成時に活用してください。
desloppify
コードベースのヘルスチェックと技術負債の追跡ツールです。コード品質、技術負債、デッドコード、大規模ファイル、ゴッドクラス、重複関数、コードスメル、命名規則の問題、インポートサイクル、結合度の問題についてユーザーが質問した場合に使用してください。また、ヘルススコアの確認、次の改善項目の提案、クリーンアップ計画の作成をリクエストされた際にも対応します。29言語に対応しています。
debugging-and-error-recovery
テストが失敗したり、ビルドが壊れたり、動作が期待と異なったり、予期しないエラーが発生したりした場合に、体系的な根本原因デバッグをガイドします。推測ではなく、根本原因を見つけて修正するための体系的なアプローチが必要な場合に使用してください。
test-driven-development
テスト駆動開発により実装を進めます。ロジックの実装、バグの修正、動作の変更など、あらゆる場面で活用できます。コードが正常に動作することを証明する必要がある場合、バグ報告を受けた場合、既存機能を修正する予定がある場合に使用してください。
incremental-implementation
変更を段階的に実施します。複数のファイルに影響する機能や変更を実装する場合に使用してください。大量のコードを一度に書こうとしている場合や、タスクが一度では完結できないほど大きい場合に活用します。