designing-apis
支持REST/GraphQL API的设计和OpenAPI规范的创建。提供包括端点设计、错误处理和安全措施的全面API规范。在需要新API设计、API规范标准化和接口设计时使用。
📖 中文导读:支持REST/GraphQL API的设计和OpenAPI规范的创建。提供包括端点设计、错误处理和安全措施的全面API规范。在需要新API设计、API规范标准化和接口设计时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。
name: designing-apis description: REST/GraphQL APIの設計と OpenAPI 仕様の作成を支援します。エンドポイント設計、エラー処理、セキュリティ対策を含む包括的なAPI仕様を提供します。新規API設計、API仕様の標準化、インターフェース設計が必要な場合に使用してください。
API設計とドキュメント
概要
REST/GraphQL APIの設計からドキュメント作成までを体系的に支援するスキルです。
実行フロー
Step 1: 要件分析
情報収集
- データモデルとビジネス要件の理解
- 利用者(クライアント)のニーズ把握
- セキュリティ・パフォーマンス要件の確認
- 既存システムとの統合要件
技術選定
- REST vs GraphQL: ユースケースに応じた選択
- 認証方式: OAuth2、JWT、APIキー
- バージョニング戦略: URLパス、ヘッダー、クエリパラメータ
- レート制限とキャッシュ戦略
Step 2: API設計
RESTful API設計
リソース指向URL:
# CRUD操作
GET /api/v1/users # ユーザー一覧
POST /api/v1/users # ユーザー作成
GET /api/v1/users/{id} # ユーザー取得
PUT /api/v1/users/{id} # ユーザー更新(全体)
PATCH /api/v1/users/{id} # ユーザー更新(部分)
DELETE /api/v1/users/{id} # ユーザー削除
# ネストリソース
GET /api/v1/users/{id}/orders # ユーザーの注文一覧
# フィルタ・ページネーション
GET /api/v1/users?role=admin&page=2&limit=20
HTTPステータスコード:
| コード | 用途 | 使用例 |
|---|---|---|
| 200 | 成功(データあり) | GET成功 |
| 201 | 作成成功 | POST成功 |
| 204 | 成功(データなし) | DELETE成功 |
| 400 | リクエスト不正 | パラメータエラー |
| 401 | 認証エラー | トークン無効 |
| 403 | 権限エラー | アクセス権限なし |
| 404 | リソース未発見 | 存在しないID |
| 422 | バリデーションエラー | 入力値が不正 |
| 429 | レート制限 | リクエスト制限超過 |
| 500 | サーバーエラー | 内部エラー |
エラーレスポンス形式:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "入力値が不正です",
"details": [
{
"field": "email",
"message": "有効なメールアドレスを入力してください",
"code": "INVALID_EMAIL"
}
],
"request_id": "abc123"
}
}
GraphQL API設計
スキーマ定義:
type User {
id: ID!
email: String!
name: String
createdAt: DateTime!
orders: [Order!]!
}
type Query {
user(id: ID!): User
users(filter: UserFilter, limit: Int, offset: Int): [User!]!
}
type Mutation {
createUser(input: CreateUserInput!): User!
updateUser(id: ID!, input: UpdateUserInput!): User!
deleteUser(id: ID!): Boolean!
}
Step 3: 認証・認可設計
OAuth 2.0 フロー
- Authorization Code: Webアプリ向け
- PKCE: モバイル/SPA向け
- Client Credentials: サーバー間通信
JWT構造
{
"header": { "alg": "RS256", "typ": "JWT" },
"payload": {
"sub": "user_id_123",
"iat": 1234567890,
"exp": 1234567890,
"scope": ["read", "write"]
}
}
Step 4: ドキュメント作成
OpenAPI/Swagger仕様
openapi: 3.0.0
info:
title: User API
version: 1.0.0
paths:
/users:
get:
summary: ユーザー一覧取得
security:
- bearerAuth: []
parameters:
- name: page
in: query
schema:
type: integer
responses:
'200':
description: 成功
Step 5: バージョニング戦略
URL パスによるバージョニング(推奨)
https://api.example.com/v1/users
https://api.example.com/v2/users
Step 6: レビューとフィードバック
- API設計のレビュー(一貫性、RESTful原則)
- セキュリティレビュー
- パフォーマンス要件の確認
- ドキュメントの正確性確認
出力成果物
- API設計書: エンドポイント一覧、データモデル、認証方式
- OpenAPI/Swagger仕様: 機械可読なAPI定義
- GraphQLスキーマ: 型定義とリゾルバ構成
- APIリファレンス: 全エンドポイントの詳細ドキュメント
- 認証ガイド: 認証フローと実装例
- クイックスタート: 最初のAPI呼び出しまでの手順
ベストプラクティス
- 一貫性: 命名規則、エラーレスポンス形式の統一
- セキュリティ: HTTPS必須、適切な認証・認可、レート制限
- パフォーマンス: ページネーション、キャッシュの活用
- 開発者体験: 明確なドキュメント、わかりやすいエラーメッセージ
- バージョニング: 破壊的変更の明示、十分な移行期間
関連ファイル
- TEMPLATES.md - OpenAPI/ドキュメントテンプレート
- EXAMPLES.md - 実装例集