Communitygithub.com

majiayu000/claude-skill-registry

REST 및 GraphQL API 설계 원칙을 마스터하여 직관적이고 확장 가능하며 유지보수하기 쉬운 API를 구축합니다. 새 API 설계, API 사양 검토 또는 API 설계 표준 수립 시 활용하세요.

claude-skill-registry란 무엇인가요?

이 스킬은 개발자와 AI 에이전트가 REST 및 GraphQL API를 설계, 리팩토링 및 최적화하는 방법을 안내합니다. 리소스 지향 REST 아키텍처, HTTP 메서드 의미 체계, 스키마 우선 GraphQL 개발, API 버전 전략, 페이지 매기기, 필터링, 오류 처리, HATEOAS와 같은 핵심 개념을 다룹니다. Claude Code, Cursor 또는 Codex와 같은 AI 코딩 도우미와 함께 사용하도록 설계되었으며, REST API 템플릿(Python, FastAPI) 및 GraphQL 스키마 예제(아리아드네)를 포함한 실용적인 코드 패턴을 제공합니다. 이 스킬은 N+1 쿼리 방지(DataLoader), 일관된 오류 응답 형식, 커서 기반 페이지 매기기(Relay 스타일)와 같은 모범 사례와 일반적인 함정을 강조하여 개발자가 확장 가능하고 유지 관리가 쉬운 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 설계 원칙

리소스 중심 아키텍처

  • 리소스는 명사(사용자, 주문, 제품)이며 동사가 아님
  • HTTP 메서드를 동작에 사용(GET, POST, PUT, PATCH, DELETE)
  • URL은 리소스 계층 구조를 나타냄
  • 일관된 명명 규칙 사용

HTTP 메서드 의미 체계:

  • GET: 리소스 조회(멱등성, 안전)
  • POST: 새 리소스 생성
  • PUT: 전체 리소스 교체(멱등성)
  • PATCH: 리소스 부분 업데이트
  • DELETE: 리소스 제거(멱등성)

2. GraphQL 설계 원칙

스키마 우선 개발

  • 타입은 도메인 모델 정의
  • 쿼리는 데이터 읽기용
  • 뮤테이션은 데이터 수정용
  • 서브스크립션은 실시간 업데이트용

쿼리 구조:

  • 클라이언트는 필요한 것만 요청
  • 단일 엔드포인트, 여러 작업
  • 강력한 타입 시스템을 갖춘 스키마
  • 인트로스펙션 내장

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="페이지당 항목 수")

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} not found",
            "details": {"id": id}
        }
    )

def raise_validation_error(errors: List[ValidationErrorDetail]):
    raise HTTPException(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        detail={
            "error": "ValidationError",
            "message": "Request validation failed",
            "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 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 확인을 위해 하나 더 가져오기
        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:
    """사용자의 주문을 조회합니다(N+1 문제 방지를 위해 DataLoader 사용)."""
    # 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)

        # 사용자 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. 일관된 명명: 컬렉션에는 복수형 명사 사용(/user가 아닌 /users)
  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.

관련 스킬