Communitygithub.com

API 설계 원칙

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

API 설계 원칙란 무엇인가요?

이 스킬은 REST와 GraphQL API 설계의 핵심 원칙을 제공하여 개발자가 직관적이고 확장 가능하며 유지보수성이 뛰어난 API를 설계할 수 있도록 돕습니다. RESTful 설계 원칙(리소스 지향 아키텍처, HTTP 메서드 시맨틱스), GraphQL 설계 원칙(스키마 우선 개발, 쿼리 구조), API 버전 관리 전략 등 핵심 개념을 다룹니다. 또한 FastAPI와 Python을 기반으로 한 구체적인 REST API 디자인 패턴(리소스 컬렉션, 페이지네이션/필터링, 오류 처리, HATEOAS)과 Ariadne 및 DataLoader를 활용한 GraphQL 디자인 패턴(스키마 설계, 리졸버 설계, N+1 문제 방지)을 코드 예제와 함께 제공합니다. Claude Code, Cursor 등 협업 코딩 AI 도구와 함께 사용하여 API 설계 리뷰, 표준 수립, 문서화 등에 활용할 수 있습니다.

지원 대상✓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 설계 원칙

리소스 지향 아키텍처

  • 리소스는 명사(사용자, 주문, 제품)이며 동사가 아닙니다.
  • 작업에는 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}을(를) 찾을 수 없습니다",
            "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 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:
    """사용자의 주문 조회 (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".

관련 스킬