api-design

What this skill does

When applied, it prepends a system prompt before your request is sent — no extra calls and no change to how you are billed beyond the added tokens.

---
name: api-design
description: リソース命名、ステータス コード、ページネーション、フィルタリング、エラー応答、バージョン管理、およびレート制限を含む REST API デザイン パターン。
origin: ECC
---

# API デザイン パターン

一貫性のある開発者フレンドリーな REST API を設計するための規約とベスト プラクティス。

## アクティブ化するとき

- 新しい API エンドポイントを設計しているとき
- 既存の API 契約をレビューしているとき
- ページネーション、フィルタリング、またはソートを追加しているとき
- API のエラー処理を実装しているとき
- API バージョン管理戦略を計画しているとき
- パブリックまたはパートナー向けの API を構築しているとき

## リソース デザイン

### URL 構造

```
# リソースは名詞、複数形、小文字、ケバブケース
GET    /api/v1/users
GET    /api/v1/users/:id
POST   /api/v1/users
PUT    /api/v1/users/:id
PATCH  /api/v1/users/:id
DELETE /api/v1/users/:id

# 関係のための サブ リソース
GET    /api/v1/users/:id/orders
POST   /api/v1/users/:id/orders

# CRUD にマップされないアクション (動詞は慎重に使用)
POST   /api/v1/orders/:id/cancel
POST   /api/v1/auth/login
POST   /api/v1/auth/refresh
```

### 命名規則

```
# よい
/api/v1/team-members          # 複数単語リソース用ケバブケース
/api/v1/orders?status=active  # フィルタリング用クエリ パラメーター
/api/v1/users/123/orders      # 所有権用のネストされたリソース

# 悪い
/api/v1/getUsers              # URL 内の動詞
/api/v1/user                  # 単数形（複数形を使用）
/api/v1/team_members          # URL 内のスネークケース
/api/v1/users/123/getOrders   # ネストされたリソース内の動詞
```

## HTTP メソッドとステータス コード

### メソッド セマンティクス

| メソッド | べき等 | セーフ | 使用対象 |
|--------|--------|--------|---------|
| GET | はい | はい | リソースを取得 |
| POST | いいえ | いいえ | リソースを作成、アクションをトリガー |
| PUT | はい | いいえ | リソースの完全な置換 |
| PATCH | いいえ* | いいえ | リソースの部分的な更新 |
| DELETE | はい | いいえ | リソースを削除 |

*PATCH は適切な実装でべき等にすることができます

### ステータス コード リファレンス

```
# 成功
200 OK                    — GET、PUT、PATCH（応答本体付き）
201 Created               — POST (Location ヘッダーを含める)
204 No Content            — DELETE、PUT（応答本体なし）

# クライアント エラー
400 Bad Request           — 検証失敗、不正な JSON
401 Unauthorized          — 認証がない、または無効
403 Forbidden             — 認証済みですが認可されていない
404 Not Found             — リソースが存在しません
409 Conflict              — 重複エントリ、状態競合
422 Unprocessable Entity  — セマンティック上無効（有効な JSON、悪いデータ）
429 Too Many Requests     — レート制限を超過

# サーバー エラー
500 Internal Server Error — 予期しない失敗 (詳細は公開しない)

Use this skill

{
  "model": "gpt-4o-mini",
  "skill": "imp-941b6acb-5fb3-41a6-b5e6-b35e507c26fb",
  "messages": [{ "role": "user", "content": "…" }]
}

More skills