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
- 일관된 명명: 컬렉션에는 복수 명사를 사용하세요. (
/users,/user가 아님) - 무상태: 각 요청에는 필요한 모든 정보가 포함되어야 합니다.
- HTTP 상태 코드 올바르게 사용: 2xx 성공, 4xx 클라이언트 오류, 5xx 서버 오류
- API 버전 관리: 처음부터 호환성이 깨지는 변경을 계획하세요.
- 페이지네이션: 큰 컬렉션은 항상 페이지네이션하세요.
- 속도 제한: API를 속도 제한으로 보호하세요.
- 문서화: 대화형 문서를 위해 OpenAPI/Swagger를 사용하세요.
GraphQL API
- 스키마 우선: 리졸버를 작성하기 전에 스키마를 설계하세요.
- N+1 문제 방지: 효율적인 데이터 가져오기를 위해 DataLoader를 사용하세요.
- 입력 유효성 검사: 스키마 및 리졸버 수준에서 검증하세요.
- 오류 처리: 뮤테이션 페이로드에서 구조화된 오류를 반환하세요.
- 페이지네이션: 커서 기반 페이지네이션(Relay 스펙)을 사용하세요.
- 폐기: 점진적 마이그레이션을 위해
@deprecated지시어를 사용하세요. - 모니터링: 쿼리 복잡도와 실행 시간을 추적하세요.
일반적인 함정
- 과도한 가져오기/부족한 가져오기 (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 스펙 생성