mcpField
R
rest-api-design

rest-api-design

github.com/aj-geddes開発3732.1k 回インストール34 週間前に更新
リポジトリ

rest-api-design について

REST API を新規作成または改修する開発者向けの設計手法です。一貫したリソース指向のエンドポイント、リクエストとレスポンス形式、バージョン管理、API ドキュメントを扱います。

主な機能

  1. 01リソース命名と HTTP メソッド
  2. 02クエリとレスポンス形式の指針
  3. 03ステータスコードとバージョン管理
  4. 04認証とレート制限の指針
  5. 05OpenAPI ドキュメント

活用シーン

  1. 01新しい REST API のエンドポイント設計
  2. 02リクエストとレスポンス形式の統一
  3. 03API バージョン管理の計画
  4. 04OpenAPI による API ドキュメント作成

インストール

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

$npx skills add https://github.com/aj-geddes/useful-ai-prompts --skill rest-api-design

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

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
complete-example-expressjs.md
http-status-codes.md
openapi-documentation.md
query-parameters.md
request-examples.md
resource-naming.md
response-formats.md
scripts/
validate-api.sh
templates/
api-scaffold.yaml

詳細

REST API の設計

目次

概要

リソース指向アーキテクチャに関する業界のベストプラクティスに従い、直感的で一貫性のある REST API を設計します。

使用する場面

  • 新しい RESTful API を設計する
  • エンドポイントの構造を作成する
  • リクエスト／レスポンスの形式を定義する
  • API のバージョン管理を実装する
  • API 仕様を文書化する
  • 既存の API をリファクタリングする

クイックスタート

最小限の動作例：

✅ Good Resource Names (Nouns, Plural)
GET    /api/users
GET    /api/users/123
GET    /api/users/123/orders
POST   /api/products
DELETE /api/products/456

❌ Bad Resource Names (Verbs, Inconsistent)
GET    /api/getUsers
POST   /api/createProduct
GET    /api/user/123  (inconsistent singular/plural)

リファレンスガイド

references/ ディレクトリにある詳細な実装：

ガイド内容
リソースの命名リソースの命名、HTTP メソッドと操作
リクエスト例リクエスト例
クエリパラメータークエリパラメーター
レスポンス形式レスポンス形式
HTTP ステータスコードHTTP ステータスコード、API のバージョン管理、認証とセキュリティ、レート制限ヘッダー
OpenAPI ドキュメントOpenAPI ドキュメント
完全な例：Express.jsconst express = require("express");

ベストプラクティス

✅ 推奨事項
  • リソースには動詞ではなく名詞を使います
  • コレクションには複数形の名前を使います
  • 命名規則に一貫性を持たせます
  • 適切な HTTP ステータスコードを返します
  • コレクションにはページネーションを含めます
  • フィルタリングと並べ替えのオプションを提供します
  • API にバージョンを付けます
  • OpenAPI を使って十分に文書化します
  • HTTPS を使います
  • レート制限を実装します
  • 明確なエラーメッセージを提供します
  • 日付には ISO 8601 を使います
❌ 禁止事項
  • エンドポイント名に動詞を使う
  • エラーに対して 200 を返す
  • 内部 ID を不必要に公開する
  • リソースを過度にネストする（最大 2 階層）
  • 一貫性のない命名を使う
  • 認証を忘れる
  • 機密データを返す
  • バージョン管理なしで後方互換性を破る

コメント

Markdown 対応