api-designlisted
Install: claude install-skill Saigetsu233/harness-jp-si
# API 設計支援スキル
## 1. 入力
- ユースケース · 受入基準
- 関連データモデル · ドメインオブジェクト
- 非機能要件（性能 · 可用性 · セキュリティ）
- 連携先（顧客 · 内部システム · 第三者）の制約
## 2. 設計の観点（チェックリスト）
### 2.1 エンドポイント設計
- [ ] リソース指向（名詞ベース）：`/users/{id}/orders` ◯、`/getUserOrders` ×
- [ ] 動詞は HTTP メソッド：GET / POST / PUT / PATCH / DELETE
- [ ] 階層は 2 段までを推奨：`/users/{id}/orders/{orderId}` まで、3 段以上は再考
- [ ] 一覧と単体の区別：`/users` （複数）vs `/users/{id}`（単体）
- [ ] フィルタリング · ページング · ソート：`?status=active&page=2&limit=20&sort=-createdAt`
### 2.2 リクエスト
- [ ] スキーマを明示（OpenAPI / JSON Schema / Protobuf）
- [ ] 必須 / 任意の区別
- [ ] 型 · 範囲 · パターン制約
- [ ] バリデーションエラー時のメッセージ構造
### 2.3 レスポンス
- [ ] 成功時のステータスコード：200 / 201 / 204 を適切に
- [ ] エラー時の構造（一貫性）：
```json
{
"error": {
"code": "USER_NOT_FOUND",
"message": "Human readable message",
"details": [{ "field": "email", "issue": "INVALID_FORMAT" }],
"traceId": "abc-123"
}
}
```
- [ ] エンベロープを使うかフラットか（プロジェクトで一貫）
- [ ] ページング情報（`?cursor` か `?page` か）
### 2.4 ステータスコード
| コード | 用途 |
| --- | --- |
| 200 | 成功（GET / PUT / PATCH） |
| 201 | 作成成功（POST） |
| 204 | 成功 + 内容なし（DELETE） |
| 400 | バリデーションエラー |
| 401 | 未認証 |
| 403 | 認可不足 |
| 404 | リソース不在 |
| 409 | 競合（重複登録 · バージョン不一致） |
| 422 | 業務ロジック上の拒否 |
| 429 | レート制限超過 |
| 500 | サーバ内部エラー |
| 502 / 503 / 504 | 上流障害 |
### 2.5 認証 · 認可
- [ ] 認証方式（OAuth2 / JWT / API Key / mTLS）
- [ ] スコープ · 権限の設計（最小権限）
- [ ] 認可チェックの **サーバ側必須**（クライアント信頼禁止）
### 2.6 非機能
- [ ] タイムアウト：呼出側 · サーバ側ともに数値で定義
- [ ] リトライポリシー：冪等性を保てる場合のみ自動リトライ可（POST は基本不可）
- [ ] レート制限：エンドポイント別 · 認証別
- [ ] サーキットブ