Google JSON Style Guide

https://google.github.io/styleguide/jsoncstyleguide.xml

Google의 JSON Style Guide는 JSON 데이터의 일관성과 가독성을 높이기 위한 규칙과 권장사항을 제시한다. 주요 요점을 아래와 같이 정리할 수 있다.

{
  "apiVersion": "...",
  "context": "...",
  "id": "...",
  "method": "...",
  "params": { ... },
  "data": { ... },
  "error": { ... }
}

• 최상위 필드들
  • apiVersion: 이 API의 버전 ("v1" 등)
  • context: 이 요청이 어떤 컨텍스트에서 발생했는지 설명 (예: 트래킹 ID)
  • id: 요청 또는 응답의 고유 식별자
  • method: 호출할 메서드 이름 (RPC 스타일일 때 사용)
  • params: 호출할 메서드에 전달할 인자들 (파라미터 객체)
  • data: 성공 시 응답
  • error: 실패 시 응답

data와 error는 동시에 포함되면 안 되고, 둘 중 하나만 있어야 한다.

data 객체 (성공 시 응답)

실제로 유저가 받고자 하는 데이터를 포함한다.
대부분의 유용한 정보는 이 안에 들어간다.

• kind: 리소스 종류 (예: "calendar#event")
• fields: 필드 필터링용 (필요한 필드만 지정할 때 사용)
• etag: 데이터의 버전(캐싱 용도)
• id: 데이터 자체의 ID
• lang: 언어 코드 ("en", "ko")
• updated: 마지막 수정 날짜 (RFC 3339 형식)
• deleted: 삭제 여부 (boolean)
• currentItemCount, totalItems, itemsPerPage, startIndex, pageIndex, totalPages: 페이지네이션 관련 정보
• pageLinkTemplate: 페이지 링크 형식 템플릿
• next, nextLink, previous, previousLink, self, selfLink, edit, editLink: 링크 객체들 (REST 스타일 탐색을 위한 링크)
• items: 실제 데이터 배열 (예: 게시글 리스트, 유저 리스트 등)

error 객체 (오류 발생 시 응답)

요청이 실패했을 때 포함된다. data는 이 경우 생략된다.

• code: 에러 코드 (HTTP 상태 코드와 유사)
• message: 에러 메시지 (사용자 또는 개발자용)
• errors: 에러 상세 항목들 (복수 가능)
• errors[].domain: 에러가 발생한 도메인 (예: "global" 등)
• errors[].reason: 발생 이유 (예: "notFound" 등)
• errors[].message: 구체적 설명
• errors[].location: 어떤 파라미터에서 에러가 났는지
• errors[].locationType: 예: "parameter"
• errors[].extendedHelp: 추가 설명 URL
• errors[].sendReport: 버그 리포트 제출 링크

결론

이 가이드는 API 설계자와 개발자들이 상호운용성, 유지보수성, 일관성을 확보하는 데 큰 도움이 된다.