API Response Convention

[HwangSlater]

API Response Convention

1. 규칙

• 모든 API 응답은 동일한 포맷을 따른다.
  • 성공 응답: data + meta
  • 실패 응답: code, message, status, details, meta
• meta 객체는 모든 응답에 포함된다.
  • timestamp: ISO 8601 형식의 응답 생성 시각
  • request_id: UUID, 로그 추적 및 디버깅에 활용
• HTTP Status Code와 status 필드는 반드시 일치해야 한다.
  • 예: HTTP 404 → "status": "NOT_FOUND"
• 에러 메시지는 사용자 친화적으로 작성한다.
  • 민감한 내부 정보는 details에 포함하고, 외부 응답에는 최소화
• INTERNAL_SERVER_ERROR의 경우, details는 응답에 포함하지 않고 서버 로그에서만 확인 가능하게 처리한다.

---

2. 응답 형식

✅ 성공 응답

{
  "data": {
    "user_id": 1,
    "email": "test@example.com",
    "name": "홍길동",
    "partner_id": 15,
    "partner_name": "길동상점",
    "category_ids": [2, 5, 7],
    "created_at": "2025-08-13T12:34:56"
  },
  "meta": {
    "timestamp": "2025-08-13T15:32:10.123",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

---

❌ 실패 응답 (예: 유효성 검증 실패)

{
  "code": "VALIDATION_ERROR",
  "message": "이메일 형식이 올바르지 않습니다.",
  "status": 422,
  "details": "email 필드 값이 RFC 5322 형식에 맞지 않음",
  "meta": {
    "timestamp": "2025-08-13T15:33:10.456",
    "request_id": "660e8400-e29b-41d4-a716-446655440111"
  }
}

❌ 실패 응답 (예: 서버 내부 오류, 민감 정보 미노출)

{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "서버에서 문제가 발생했습니다. 잠시 후 다시 시도해주세요.",
  "status": 503,
  "meta": {
    "timestamp": "2025-08-13T15:34:22.789",
    "request_id": "770e8400-e29b-41d4-a716-446655440222"
  }
}

주의: details는 서버에서만 볼 수 있게 로그만 남기고 클라이언트 응답에는 포함하지 않는다.