API 응답 구조 설계

기본 패턴

{
  "data": {
    "id": 101,
    "title": "JSON Guide"
  },
  "meta": {
    "requestId": "req_123",
    "version": 1
  }
}

설명

• API 응답은 대개 최상위를 object로 두는 편이 확장에 유리합니다. 나중에 meta, error, paging 같은 필드를 추가하기 쉽기 때문입니다.
• 성공 데이터와 부가 정보를 분리하면 소비자가 필요한 부분을 안정적으로 찾을 수 있습니다.
• 에러 응답도 string 하나보다 code, message, details처럼 구조화해 두는 편이 디버깅과 자동 처리에 유리합니다.
• 배열을 최상위로 바로 반환하면 단기적으로는 간단하지만, 이후 메타데이터를 넣을 때 응답 구조를 깨야 할 수 있습니다.
• 응답 구조는 "현재 필드 수"보다 "앞으로 무엇이 더 붙을 수 있는가"를 기준으로 잡는 편이 좋습니다.

짧은 예제

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "title is required"
  }
}

빠른 정리

주의할 점