api-design-principles

사용 방법

설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.

npx skills add https://github.com/secondsky/claude-skills --skill api-design-principles

시작 전 확인

설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.

원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

API Design Principles

Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.

When to Use This Skill

Designing new REST or GraphQL APIs
Refactoring existing APIs for better usability
Establishing API design standards for your team
Reviewing API specifications before implementation
Migrating between API paradigms (REST to GraphQL, etc.)
Creating developer-friendly API documentation
Optimizing APIs for specific use cases (mobile, third-party integrations)

Core Concepts

1. RESTful Design Principles

Resource-Oriented Architecture

Resources are nouns (users, orders, products), not verbs
Use HTTP methods for actions (GET, POST, PUT, PATCH, DELETE)
URLs represent resource hierarchies
Consistent naming conventions

HTTP Methods Semantics:

GET: Retrieve resources (idempotent, safe)
POST: Create new resources
PUT: Replace entire resource (idempotent)
PATCH: Partial resource updates
DELETE: Remove resources (idempotent)

2. GraphQL Design Principles

Schema-First Development

Types define your domain model
Queries for reading data
Mutations for modifying data
Subscriptions for real-time updates

Query Structure:

Clients request exactly what they need
Single endpoint, multiple operations
Strongly typed schema
Introspection built-in

3. API Versioning Strategies

URL Versioning:

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

Header Versioning:

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

Query Parameter Versioning:

/api/users?version=1

REST API Design Patterns

Pattern 1: Resource Collection Design

python

# Good: Resource-oriented endpoints
GET    /api/users              # List users (with pagination)
POST   /api/users              # Create user
GET    /api/users/{id}         # Get specific user
PUT    /api/users/{id}         # Replace user
PATCH  /api/users/{id}         # Update user fields
DELETE /api/users/{id}         # Delete user

# Nested resources
GET    /api/users/{id}/orders  # Get user's orders
POST   /api/users/{id}/orders  # Create order for user

# Bad: Action-oriented endpoints (avoid)
POST   /api/createUser
POST   /api/getUserById
POST   /api/deleteUser

Pattern 2: Pagination and Filtering

python

from fastapi import FastAPI, Query
from pydantic import BaseModel, Field
from typing import List, Optional

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

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
    )

Pattern 3: Error Handling and Status Codes

python

from fastapi import HTTPException, status

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}
        }
    )

Pattern 4: HATEOAS (Hypermedia as the Engine of Application State)

python

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 Design Patterns

Pattern 1: Schema Design

graphql

type User {
  id: ID!
  email: String!
  name: String!
  orders(first: Int = 20, after: String): OrderConnection!
}

type OrderConnection {
  edges: [OrderEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

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

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
}

input CreateUserInput {
  email: String!
  name: String!
  password: String!
}

type CreateUserPayload {
  user: User
  errors: [Error!]
}

Pattern 2: DataLoader (N+1 Prevention)

python

from aiodataloader import DataLoader

class UserLoader(DataLoader):
    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]

Best Practices

REST APIs

Consistent Naming: Use plural nouns for collections
Stateless: Each request contains all necessary information
Use HTTP Status Codes Correctly: 2xx success, 4xx client errors, 5xx server errors
Version Your API: Plan for breaking changes from day one
Pagination: Always paginate large collections
Rate Limiting: Protect your API with rate limits
Documentation: Use OpenAPI/Swagger for interactive docs

GraphQL APIs

Schema First: Design schema before writing resolvers
Avoid N+1: Use DataLoaders for efficient data fetching
Input Validation: Validate at schema and resolver levels
Error Handling: Return structured errors in mutation payloads
Pagination: Use cursor-based pagination (Relay spec)
Deprecation: Use @deprecated directive for gradual migration
Monitoring: Track query complexity and execution time

Common Pitfalls

Over-fetching/Under-fetching (REST): Fixed in GraphQL but requires DataLoaders
Breaking Changes: Version APIs or use deprecation strategies
Inconsistent Error Formats: Standardize error responses
Missing Rate Limits: APIs without limits are vulnerable to abuse
Poor Documentation: Undocumented APIs frustrate developers
Ignoring HTTP Semantics: POST for idempotent operations breaks expectations
Tight Coupling: API structure shouldn't mirror database schema

사용 방법

시작 전 확인

API Design Principles

When to Use This Skill

Core Concepts

1. RESTful Design Principles

2. GraphQL Design Principles

3. API Versioning Strategies

REST API Design Patterns

Pattern 1: Resource Collection Design

Pattern 2: Pagination and Filtering

Pattern 3: Error Handling and Status Codes

Pattern 4: HATEOAS (Hypermedia as the Engine of Application State)

GraphQL Design Patterns

Pattern 1: Schema Design

Pattern 2: DataLoader (N+1 Prevention)

Best Practices

REST APIs

GraphQL APIs

Common Pitfalls

관련 작업

더 많은 Skills

plan-interview

api-contract-testing

api-testing

csrf-protection

api-design-principles

사용 방법

시작 전 확인

API Design Principles

When to Use This Skill

Core Concepts

1. RESTful Design Principles

2. GraphQL Design Principles

3. API Versioning Strategies

REST API Design Patterns

Pattern 1: Resource Collection Design

Pattern 2: Pagination and Filtering

Pattern 3: Error Handling and Status Codes

Pattern 4: HATEOAS (Hypermedia as the Engine of Application State)

GraphQL Design Patterns

Pattern 1: Schema Design

Pattern 2: DataLoader (N+1 Prevention)

Best Practices

REST APIs

GraphQL APIs

Common Pitfalls

관련 작업

backend-patterns

python-patterns

rea-analysis-optimization

codebase-design

더 많은 Skills

plan-interview

api-contract-testing

api-testing

csrf-protection