Communitygithub.com

majiayu000/claude-skill-registry

REST と GraphQL の API 設計原則を習得し、直感的でスケーラブルかつ保守性の高い API を構築します。新しい API の設計時、API 仕様のレビュー時、または API 設計標準の確立時に使用します。

claude-skill-registry とは?

このスキルは、開発者が直感的でスケーラブル、かつ保守性の高い REST および GraphQL API を設計するための包括的なガイドを提供します。API 設計のベストプラクティス、バージョニング戦略、エラーハンドリング、そしてパフォーマンス最適化のためのパターンを網羅しています。REST ではリソース指向の設計、HTTP メソッドの適切な使用、ページネーションや HATEOAS パターンに焦点を当て、GraphQL ではスキーマファースト開発、データローダーによる N+1 問題の防止、カーソルベースのページネーションなどを扱います。主に Claude Code や Cursor、Codex などの AI エージェントと連携して使用することを想定しており、Python と FastAPI、また Ariadne や aiodataloader を用いた GraphQL リゾルバのコード例も豊富に含まれています。このスキルを利用することで、API 設計の標準化、開発者体験の向上、そして長期的な保守性の高い API 基盤の構築が可能になります。

対応✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry/tree/HEAD/skills/api/api-design-principles-algusaem-algusaem-portfolio

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

API 設計原則

REST と GraphQL の API 設計原則を習得し、直感的でスケーラブル、かつ保守性の高い API を構築して、開発者を魅了し、時代に耐えるものにしましょう。

このスキルを使用するタイミング

  • 新しい REST または GraphQL API を設計する場合
  • 既存の API をより使いやすくリファクタリングする場合
  • チームの API 設計標準を確立する場合
  • 実装前に API 仕様をレビューする場合
  • API パラダイム間の移行(REST から GraphQL など)を行う場合
  • 開発者にとって使いやすい API ドキュメントを作成する場合
  • 特定のユースケース(モバイル、サードパーティ連携など)向けに API を最適化する場合

中核概念

1. RESTful 設計原則

リソース指向アーキテクチャ

  • リソースは名詞(users、orders、products)であり動詞ではない
  • アクションには HTTP メソッドを使用(GET、POST、PUT、PATCH、DELETE)
  • URL はリソース階層を表現する
  • 一貫性のある命名規則を使用する

HTTP メソッドのセマンティクス:

  • GET: リソースの取得(べき等、安全)
  • POST: 新しいリソースの作成
  • PUT: リソース全体の置き換え(べき等)
  • PATCH: リソースの部分更新
  • DELETE: リソースの削除(べき等)

2. GraphQL 設計原則

スキーマファースト開発

  • 型(Types)がドメインモデルを定義する
  • クエリ(Queries)はデータ読み取り用
  • ミューテーション(Mutations)はデータ変更用
  • サブスクリプション(Subscriptions)はリアルタイム更新用

クエリ構造:

  • クライアントは必要なものを正確にリクエストする
  • 単一のエンドポイント、複数の操作
  • 厳密に型付けされたスキーマ
  • イントロスペクションが組み込まれている

3. API バージョニング戦略

URL バージョニング:

/api/v1/users
/api/v2/users

ヘッダーバージョニング:

Accept: application/vnd.api+json; version=1

クエリパラメータバージョニング:

/api/users?version=1

REST API 設計パターン

パターン 1: リソースコレクション設計

# Good: リソース指向のエンドポイント
GET    /api/users              # ユーザー一覧(ページネーション付き)
POST   /api/users              # ユーザーを作成
GET    /api/users/{id}         # 特定のユーザーを取得
PUT    /api/users/{id}         # ユーザーを置き換え
PATCH  /api/users/{id}         # ユーザーフィールドを更新
DELETE /api/users/{id}         # ユーザーを削除

# ネストされたリソース
GET    /api/users/{id}/orders  # ユーザーの注文を取得
POST   /api/users/{id}/orders  # ユーザーの注文を作成

# Bad: アクション指向のエンドポイント(避ける)
POST   /api/createUser
POST   /api/getUserById
POST   /api/deleteUser

パターン 2: ページネーションとフィルタリング

from typing import List, Optional
from pydantic import BaseModel, Field

class PaginationParams(BaseModel):
    page: int = Field(1, ge=1, description="ページ番号")
    page_size: int = Field(20, ge=1, le=100, description="1ページあたりのアイテム数")

class FilterParams(BaseModel):
    status: Optional[str] = None
    created_after: Optional[str] = None
    search: Optional[str] = None

class PaginatedResponse(BaseModel):
    items: List[dict]
    total: int
    page: int
    page_size: int
    pages: int

    @property
    def has_next(self) -> bool:
        return self.page < self.pages

    @property
    def has_prev(self) -> bool:
        return self.page > 1

# FastAPI エンドポイントの例
from fastapi import FastAPI, Query, Depends

app = FastAPI()

@app.get("/api/users", response_model=PaginatedResponse)
async def list_users(
    page: int = Query(1, ge=1),
    page_size: int = Query(20, ge=1, le=100),
    status: Optional[str] = Query(None),
    search: Optional[str] = Query(None)
):
    # フィルターを適用
    query = build_query(status=status, search=search)

    # 総数をカウント
    total = await count_users(query)

    # ページを取得
    offset = (page - 1) * page_size
    users = await fetch_users(query, limit=page_size, offset=offset)

    return PaginatedResponse(
        items=users,
        total=total,
        page=page,
        page_size=page_size,
        pages=(total + page_size - 1) // page_size
    )

パターン 3: エラーハンドリングとステータスコード

from fastapi import HTTPException, status
from pydantic import BaseModel

class ErrorResponse(BaseModel):
    error: str
    message: str
    details: Optional[dict] = None
    timestamp: str
    path: str

class ValidationErrorDetail(BaseModel):
    field: str
    message: str
    value: Any

# 一貫性のあるエラーレスポンス
STATUS_CODES = {
    "success": 200,
    "created": 201,
    "no_content": 204,
    "bad_request": 400,
    "unauthorized": 401,
    "forbidden": 403,
    "not_found": 404,
    "conflict": 409,
    "unprocessable": 422,
    "internal_error": 500
}

def raise_not_found(resource: str, id: str):
    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail={
            "error": "NotFound",
            "message": f"{resource} が見つかりません",
            "details": {"id": id}
        }
    )

def raise_validation_error(errors: List[ValidationErrorDetail]):
    raise HTTPException(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        detail={
            "error": "ValidationError",
            "message": "リクエストのバリデーションに失敗しました",
            "details": {"errors": [e.dict() for e in errors]}
        }
    )

# 使用例
@app.get("/api/users/{user_id}")
async def get_user(user_id: str):
    user = await fetch_user(user_id)
    if not user:
        raise_not_found("User", user_id)
    return user

パターン 4: HATEOAS(アプリケーション状態のエンジンとしてのハイパーメディア)

class UserResponse(BaseModel):
    id: str
    name: str
    email: str
    _links: dict

    @classmethod
    def from_user(cls, user: User, base_url: str):
        return cls(
            id=user.id,
            name=user.name,
            email=user.email,
            _links={
                "self": {"href": f"{base_url}/api/users/{user.id}"},
                "orders": {"href": f"{base_url}/api/users/{user.id}/orders"},
                "update": {
                    "href": f"{base_url}/api/users/{user.id}",
                    "method": "PATCH"
                },
                "delete": {
                    "href": f"{base_url}/api/users/{user.id}",
                    "method": "DELETE"
                }
            }
        )

GraphQL 設計パターン

パターン 1: スキーマ設計

# schema.graphql

# 明確な型定義
type User {
  id: ID!
  email: String!
  name: String!
  createdAt: DateTime!

  # リレーションシップ
  orders(first: Int = 20, after: String, status: OrderStatus): OrderConnection!

  profile: UserProfile
}

type Order {
  id: ID!
  status: OrderStatus!
  total: Money!
  items: [OrderItem!]!
  createdAt: DateTime!

  # 逆参照
  user: User!
}

# ページネーションパターン(Relay スタイル)
type OrderConnection {
  edges: [OrderEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type OrderEdge {
  node: Order!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

# 型安全性のための Enum
enum OrderStatus {
  PENDING
  CONFIRMED
  SHIPPED
  DELIVERED
  CANCELLED
}

# カスタムスカラー
scalar DateTime
scalar Money

# クエリルート
type Query {
  user(id: ID!): User
  users(first: Int = 20, after: String, search: String): UserConnection!

  order(id: ID!): Order
}

# ミューテーションルート
type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(input: UpdateUserInput!): UpdateUserPayload!
  deleteUser(id: ID!): DeleteUserPayload!

  createOrder(input: CreateOrderInput!): CreateOrderPayload!
}

# ミューテーション用の入力型
input CreateUserInput {
  email: String!
  name: String!
  password: String!
}

# ミューテーション用のペイロード型
type CreateUserPayload {
  user: User
  errors: [Error!]
}

type Error {
  field: String
  message: String!
}

パターン 2: リゾルバ設計

from typing import Optional, List
from ariadne import QueryType, MutationType, ObjectType
from dataclasses import dataclass

query = QueryType()
mutation = MutationType()
user_type = ObjectType("User")

@query.field("user")
async def resolve_user(obj, info, id: str) -> Optional[dict]:
    """ID で単一ユーザーを解決します。"""
    return await fetch_user_by_id(id)

@query.field("users")
async def resolve_users(
    obj,
    info,
    first: int = 20,
    after: Optional[str] = None,
    search: Optional[str] = None
) -> dict:
    """ページネーションされたユーザー一覧を解決します。"""
    # カーソルをデコード
    offset = decode_cursor(after) if after else 0

    # ユーザーを取得
    users = await fetch_users(
        limit=first + 1,  # hasNextPage を確認するために1つ多く取得
        offset=offset,
        search=search
    )

    # ページネーション
    has_next = len(users) > first
    if has_next:
        users = users[:first]

    edges = [
        {
            "node": user,
            "cursor": encode_cursor(offset + i)
        }
        for i, user in enumerate(users)
    ]

    return {
        "edges": edges,
        "pageInfo": {
            "hasNextPage": has_next,
            "hasPreviousPage": offset > 0,
            "startCursor": edges[0]["cursor"] if edges else None,
            "endCursor": edges[-1]["cursor"] if edges else None
        },
        "totalCount": await count_users(search=search)
    }

@user_type.field("orders")
async def resolve_user_orders(user: dict, info, first: int = 20) -> dict:
    """ユーザーの注文を解決します(DataLoader による N+1 防止)。"""
    # DataLoader を使用してリクエストをバッチ処理
    loader = info.context["loaders"]["orders_by_user"]
    orders = await loader.load(user["id"])

    return paginate_orders(orders, first)

@mutation.field("createUser")
async def resolve_create_user(obj, info, input: dict) -> dict:
    """新規ユーザーを作成します。"""
    try:
        # 入力を検証
        validate_user_input(input)

        # ユーザーを作成
        user = await create_user(
            email=input["email"],
            name=input["name"],
            password=hash_password(input["password"])
        )

        return {
            "user": user,
            "errors": []
        }
    except ValidationError as e:
        return {
            "user": None,
            "errors": [{"field": e.field, "message": e.message}]
        }

パターン 3: DataLoader(N+1 問題の防止)

from aiodataloader import DataLoader
from typing import List, Optional

class UserLoader(DataLoader):
    """ID でユーザーをバッチロードします。"""

    async def batch_load_fn(self, user_ids: List[str]) -> List[Optional[dict]]:
        """複数のユーザーを単一のクエリでロードします。"""
        users = await fetch_users_by_ids(user_ids)

        # 結果を入力順にマッピング
        user_map = {user["id"]: user for user in users}
        return [user_map.get(user_id) for user_id in user_ids]

class OrdersByUserLoader(DataLoader):
    """ユーザー ID で注文をバッチロードします。"""

    async def batch_load_fn(self, user_ids: List[str]) -> List[List[dict]]:
        """複数ユーザーの注文を単一のクエリでロードします。"""
        orders = await fetch_orders_by_user_ids(user_ids)

        # 注文を user_id でグループ化
        orders_by_user = {}
        for order in orders:
            user_id = order["user_id"]
            if user_id not in orders_by_user:
                orders_by_user[user_id] = []
            orders_by_user[user_id].append(order)

        # 入力順に返却
        return [orders_by_user.get(user_id, []) for user_id in user_ids]

# コンテキストのセットアップ
def create_context():
    return {
        "loaders": {
            "user": UserLoader(),
            "orders_by_user": OrdersByUserLoader()
        }
    }

ベストプラクティス

REST API

  1. 一貫性のある命名: コレクションには複数形の名詞を使用する(/users、/user ではない)
  2. ステートレス: 各リクエストに必要な情報をすべて含める
  3. HTTP ステータスコードを正しく使用する: 2xx 成功、4xx クライアントエラー、5xx サーバーエラー
  4. API をバージョニングする: 初日から破壊的変更に備える
  5. ページネーション: 大規模なコレクションは常にページネーションする
  6. レート制限: API をレート制限で保護する
  7. ドキュメント: 対話型ドキュメントには OpenAPI/Swagger を使用する

GraphQL API

  1. スキーマファースト: リゾルバを作成する前にスキーマを設計する
  2. N+1 を避ける: 効率的なデータ取得に DataLoader を使用する
  3. 入力検証: スキーマとリゾルバの両方のレベルで検証する
  4. エラーハンドリング: ミューテーションペイロードで構造化されたエラーを返す
  5. ページネーション: カーソルベースのページネーションを使用する(Relay 仕様)
  6. 非推奨化: 段階的な移行には @deprecated ディレクティブを使用する
  7. モニタリング: クエリの複雑さと実行時間を追跡する

よくある落とし穴

  • 過剰取得/過小取得(REST): GraphQL では解決されるが、DataLoader が必要
  • 破壊的変更: API をバージョニングするか、非推奨化戦略を使用する
  • 一貫性のないエラーフォーマット: エラーレスポンスを標準化する
  • レート制限の欠如: 制限のない API は悪用されやすい
  • 不十分なドキュメント: ドキュメント化されていない API は開発者をイライラさせる
  • HTTP セマンティクスの無視: べき等な操作に POST を使うと期待を裏切る
  • 密結合: API 構造がデータベーススキーマを反映すべきではない

リソース

  • references/rest-best-practices.md: 包括的な REST API 設計ガイド
  • references/graphql-schema-design.md: GraphQL スキーマパターンとアンチパターン
  • references/api-versioning-strategies.md: バージョニングアプローチと移行パス
  • assets/rest-api-template.py: FastAPI REST API テンプレート
  • assets/graphql-schema-template.graphql: 完全な GraphQL スキーマ例
  • assets/api-design-checklist.md: 実装前レビューチェックリスト
  • scripts/openapi-generator.py: コードから OpenAPI 仕様を生成

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

majiayu000/claude-skill-registry

Builds, edit or validate Agent Skill through conversational discovery. Use when the user requests to "Create an Agent", "Optimize an Agent" or "Edit an Agent".

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, or asks a question about BMad

majiayu000/claude-skill-registry

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry

Portfolio allocation and rebalancing optimizer. Manages asset allocation across stocks/cash/bonds, performs periodic rebalancing, and ensures diversification according to market regime and risk tolerance.

majiayu000/claude-skill-registry

Create a hilarious and ultra-realistic video of an anthropomorphic animal acting like a human vlogger in a real-world setting.

majiayu000/claude-skill-registry

Speech-to-text transcription and translation via OpenAI Audio API -- models, response formats, timestamps, prompting, streaming, chunking, and diarization

majiayu000/claude-skill-registry

BlockRun works with Claude Code and Google Antigravity.

majiayu000/claude-skill-registry

This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.

majiayu000/claude-skill-registry

小省导购员数字人带货版即梦视频提示词生成系统,基于四大智能体协同(提示词生成师、质量管控师、知识库运维师、跨环节适配师),按照"主体+运动+场景+(镜头语言+光影+氛围)"公式输出中英文双版提示词,适配5s短视频。确保人物一致性、视觉连贯性、情绪连贯性,支持知识库智能复用和跨工具适配(Suno音乐、AI绘画),为数字人带货视频提供高质量提示词生成服务。

majiayu000/claude-skill-registry

Upload and manage files using Google Gemini File API via scripts/. Use for uploading images, audio, video, PDFs, and other files for use with Gemini models. Supports file upload, status checking, and file management. Triggers on "upload file", "file API", "upload image", "upload PDF", "upload video", "file management".

majiayu000/claude-skill-registry

CRITICAL: Use for MolyKit AI chat toolkit. Triggers on: BotClient, OpenAI, SSE streaming, AI chat, molykit, PlatformSend, spawn(), ThreadToken, cross-platform async, Chat widget, Messages, PromptInput, Avatar, LLM

majiayu000/claude-skill-registry

AI and machine learning workflow covering LLM application development, RAG implementation, agent architecture, ML pipelines, and AI-powered features.

majiayu000/claude-skill-registry

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

関連スキル