REST API 설계: Flutter 앱과 맞물리는 백엔드 구조

# 좋은 예: 복수형 명사, 소문자, 하이픈 구분
GET    /api/v1/users
GET    /api/v1/users/:id
POST   /api/v1/users
PATCH  /api/v1/users/:id
DELETE /api/v1/users/:id

# 중첩 리소스
GET    /api/v1/users/:id/orders
POST   /api/v1/users/:id/orders

# 나쁜 예
GET    /api/getUser          # 동사 사용
GET    /api/user_list         # 언더스코어
POST   /api/createNewOrder    # camelCase + 동사

// 성공 응답 — 단건
{
  "data": {
    "id": "abc123",
    "name": "홍길동",
    "email": "hong@example.com"
  }
}

// 성공 응답 — 목록 (페이지네이션 포함)
{
  "data": [...],
  "meta": {
    "total": 142,
    "page": 1,
    "limit": 20,
    "hasNext": true
  }
}

// 에러 응답
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "이메일 형식이 올바르지 않습니다",
    "details": [
      { "field": "email", "message": "유효한 이메일을 입력해주세요" }
    ]
  }
}

// api_response.dart — 공통 응답 래퍼
@freezed
class ApiResponse<T> with _$ApiResponse<T> {
  const factory ApiResponse.success({
    required T data,
    PageMeta? meta,
  }) = _Success;

  const factory ApiResponse.error({
    required ApiError error,
  }) = _Error;
}

@freezed
class PageMeta with _$PageMeta {
  const factory PageMeta({
    required int total,
    required int page,
    required int limit,
    required bool hasNext,
  }) = _PageMeta;
}

// offset 방식 — 간단하지만 데이터 변동 시 중복/누락 발생
GET /api/v1/posts?page=3&limit=20

// cursor 방식 — 무한 스크롤에 적합
GET /api/v1/posts?cursor=abc123&limit=20

// 응답
{
  "data": [...],
  "meta": {
    "nextCursor": "def456",
    "hasNext": true
  }
}