onejaejae/api-conventions

API Conventions

API 설계 시 참조하는 컨벤션입니다.

---

URL 설계

/api/{resource}           # 복수형 명사 (버전 없음)
/api/{resource}/{id}      # 단일 리소스

예시

| 동작 | URL | HTTP 메서드 | |------|-----|------------| | 목록 조회 | /api/researches | GET | | 단일 조회 | /api/researches/{research_id} | GET | | 생성 | /api/researches | POST | | 수정 | /api/researches/{research_id} | PATCH | | 삭제 | /api/researches/{research_id} | DELETE |

HTTP 메서드

| 메서드 | 용도 | 상태코드 | |--------|------|----------| | GET | 조회 | 200 | | POST | 생성 | 201 | | PATCH | 수정 | 200 | | DELETE | 삭제 | 200 또는 204 |

HTTP 상태 코드

| 코드 | 의미 | |------|------| | 200 | OK (조회/수정 성공) | | 201 | Created (생성 성공) | | 400 | Bad Request (유효성 검사 실패) | | 401 | Unauthorized (인증 필요) | | 403 | Forbidden (권한 없음) | | 404 | Not Found (리소스 없음) | | 409 | Conflict (중복) | | 500 | Internal Server Error |

---

Response 형식

성공

# 스키마 정의 (src/schemas/common.py)
class Meta(BaseModel):
    pass

class CommonResponse(BaseModel, Generic[T, M]):
    data: T
    meta: M

{
  "data": { ... },
  "meta": {}
}

에러

# 스키마 정의 (src/schemas/error.py)
class ErrorSchema(BaseModel):
    status_code: int
    message: str
    error_code: str

class ErrorResponse(BaseModel):
    error: ErrorSchema

{
  "error": {
    "status_code": 404,
    "message": "Research with id 1 not found",
    "error_code": "RESEARCH_NOT_FOUND"
  }
}

에러 코드 형식

{DOMAIN}_{ERROR_TYPE}

예시:

• AUTH_INVALID_CREDENTIALS - 인증 실패
• AUTH_TOKEN_EXPIRED - 토큰 만료
• RESEARCH_NOT_FOUND - 연구 없음
• VALIDATION_ERROR - 입력값 검증 실패

예외 클래스 매핑

| HTTP 상태 | 예외 클래스 | 사용 예시 | |-----------|-------------|-----------| | 400 | ValidationCommonException | 입력값 검증 실패 | | 401 | UnauthorizedCommonException | 인증 실패 | | 403 | PermissionCommonException | 권한 없음 | | 404 | NotFoundCommonException | 리소스 없음 | | 503 | ServiceUnavailableCommonException | 외부 서비스 장애 |

도메인별 예외 정의

# src/exceptions/research.py
from src.exceptions.common import NotFoundCommonException

class ResearchNotFoundException(NotFoundCommonException):
    pass

---

FastAPI 구현 패턴

Controller

# src/controllers/research.py
from typing import Annotated

from dependency_injector.wiring import Provide, inject
from fastapi import APIRouter, Body, Depends, Path, status
from sqlalchemy.ext.asyncio import AsyncSession

from src.containers import Container
from src.database import database
from src.schemas.common import CommonResponse, Meta
from src.schemas.error import COMMON_ERROR_RESPONSES
from src.schemas.research import ResearchCreate, ResearchResponse
from src.services.research_service import ResearchService
from src.utils.auth import CurrentUserId, RequireAuth

research_router = APIRouter(prefix="/api/researches", tags=["Research"])


@research_router.get(
    "/{research_id}",
    summary="연구 조회 API",
    description="특정 연구 정보를 조회합니다.",
    status_code=status.HTTP_200_OK,
    responses=COMMON_ERROR_RESPONSES,
)
@inject
async def get_research(
    _: RequireAuth,
    research_id: Annotated[
        int, Path(title="연구 ID", description="조회할 연구의 고유 식별자")
    ],
    session: Annotated[AsyncSession, Depends(database.get_async_session)],
    service: Annotated[ResearchService, Depends(Provide[Container.research_service])],
) -> CommonResponse[ResearchResponse, Meta]:
    result = await service.get(research_id, session=session)
    return CommonResponse(data=result, meta=Meta())


@research_router.post(
    "",
    summary="연구 생성 API",
    status_code=status.HTTP_201_CREATED,
    responses=COMMON_ERROR_RESPONSES,
)
@inject
async def create_research(
    user_id: CurrentUserId,
    request: Annotated[ResearchCreate, Body()],
    session: Annotated[AsyncSession, Depends(database.get_async_session)],
    service: Annotated[ResearchService, Depends(Provide[Container.research_service])],
) -> CommonResponse[ResearchResponse, Meta]:
    result = await service.create(
        title=request.title,
        project_id=request.project_id,
        created_by_id=user_id,
        session=session,
    )
    return CommonResponse(data=result, meta=Meta())

Service

# src/services/research_service.py
from sqlalchemy.ext.asyncio import AsyncSession

from src.repositories.research_repository import ResearchRepository
from src.schemas.research import ResearchResponse


class ResearchService:
    def __init__(
        self,
        *,
        research_repository: ResearchRepository,
    ):
        self.research_repository = research_repository

    async def get(self, research_id: int, *, session: AsyncSession) -> ResearchResponse:
        research = await self.research_repository.get_or_throw(
            research_id, session=session
        )
        return ResearchResponse.model_validate(research)

Schema (Pydantic DTO)

# src/schemas/research.py
from pydantic import BaseModel, ConfigDict, Field

from src.schemas.common import TimestampInfo


# Request
class ResearchCreate(BaseModel):
    title: str = Field(..., description="연구 제목")
    project_id: int | None = Field(None, description="프로젝트 ID")


class ResearchUpdate(BaseModel):
    title: str = Field(..., description="연구 제목")


# Response
class ResearchResponse(TimestampInfo):
    model_config = ConfigDict(from_attributes=True)

    id: int = Field(..., description="연구 ID")
    title: str = Field(..., description="연구 제목")
    project_id: int | None = Field(None, description="프로젝트 ID")
    created_by_id: int | None = Field(None, description="생성자 ID")

Repository

# src/repositories/research_repository.py
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession

from src.exceptions.research import ResearchNotFoundException
from src.models.research import Research


class ResearchRepository:
    async def get(self, research_id: int, *, session: AsyncSession) -> Research | None:
        stmt = select(Research).where(
            Research.id == research_id,
            Research.deleted_at.is_(None),  # Soft Delete 필터
        )
        result = await session.execute(stmt)
        return result.scalar_one_or_none()

    async def get_or_throw(
        self,
        research_id: int,
        *,
        session: AsyncSession,
    ) -> Research:
        research = await self.get(research_id, session=session)
        if research is None:
            raise ResearchNotFoundException(f"Research with id {research_id} not found")
        return research

---

Quick Reference

Response 템플릿

# 성공
CommonResponse(data=result, meta=Meta())

# 에러 (자동 처리)
raise ResearchNotFoundException(f"Research with id {id} not found")

인증 패턴

# 인증만 필요 (사용자 ID 불필요)
_: RequireAuth

# 사용자 ID 필요
user_id: CurrentUserId

체크리스트

• [ ] URL이 복수형 명사인가? (/api/researches)
• [ ] HTTP 메서드가 적절한가? (GET/POST/PATCH/DELETE)
• [ ] 상태 코드가 올바른가? (GET 200, POST 201, DELETE 204)
• [ ] Response 형식이 CommonResponse[T, Meta] 인가?
• [ ] responses=COMMON_ERROR_RESPONSES 포함되었는가?
• [ ] @inject 데코레이터가 있는가?
• [ ] 의존성이 Annotated[Type, Depends(...)] 형식인가?