Communitygithub.com

majiayu000/claude-skill-registry-data

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

claude-skill-registry-data とは?

このスキルは、REST と GraphQL の両方の API 設計原則を網羅した包括的なガイドです。開発者や技術リーダーが、直感的でスケーラブルかつ保守性の高い API を設計、レビュー、標準化するための実践的な知識を提供します。主要な概念として、RESTful のリソース指向アーキテクチャや HTTP メソッドの適切な使用方法、GraphQL のスキーマファースト開発や DataLoader による N+1 問題の防止などが含まれます。このスキルは、Claude Code、Cursor、Codex などの AI エージェントと共に使用することを想定しており、FastAPI を使った Python コード例や Ariadne を使った GraphQL リゾルバ例など、具体的な実装パターンを通じて学習できます。API のバージョニング戦略、ページネーション、エラーハンドリング、HATEOAS といった高度なトピックもカバーしており、実プロジェクトですぐに応用可能なベストプラクティスを習得できます。

対応✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry-data/tree/HEAD/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: リソースコレクションの設計

# 良い例: リソース指向のエンドポイント
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  # ユーザーの注文を作成

# 悪い例: アクション指向のエンドポイント(避けるべき)
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

# 明確な型定義
scalar DateTime
scalar Money

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
}

# クエリルート
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-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

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-data

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-data

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-data

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-data

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-data

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

majiayu000/claude-skill-registry-data

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-data

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

majiayu000/claude-skill-registry-data

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-data

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-data

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-data

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

majiayu000/claude-skill-registry-data

Conduct domain and industry research. Use when the user says "lets create a research report on [domain or industry]

majiayu000/claude-skill-registry-data

Conduct market research on competition and customers. Use when the user says "create a market research report about [business idea]".

majiayu000/claude-skill-registry-data

Conduct technical research on technologies and architecture. Use when the user says "create a technical research report on [topic]".

majiayu000/claude-skill-registry-data

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".

関連スキル