JSON API

JSON:API의 구조

• data: 실제 리소스 데이터

• atrributes: 리소스의 속성

• relationships: 다른 리소스와의 관계

• included: 관계에 따라 포함되는 다른 리소스

• meta, links, errors: 부가 정보, 링크, 에러 정보 등

JSON:API 응답 예시

{
  "links": {
    "self": "http://example.com/articles",
    "next": "http://example.com/articles?page[offset]=2",
    "last": "http://example.com/articles?page[offset]=10"
  },
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    },
    "relationships": {
      "author": {
        "links": {
          "self": "http://example.com/articles/1/relationships/author",
          "related": "http://example.com/articles/1/author"
        },
        "data": { "type": "people", "id": "9" }
      },
      "comments": {
        "links": {
          "self": "http://example.com/articles/1/relationships/comments",
          "related": "http://example.com/articles/1/comments"
        },
        "data": [
          { "type": "comments", "id": "5" },
          { "type": "comments", "id": "12" }
        ]
      }
    },
    "links": {
      "self": "http://example.com/articles/1"
    }
  }],
  "included": [{
    "type": "people",
    "id": "9",
    "attributes": {
      "firstName": "Dan",
      "lastName": "Gebhardt",
      "twitter": "dgeb"
    },
    "links": {
      "self": "http://example.com/people/9"
    }
  }, {
    "type": "comments",
    "id": "5",
    "attributes": {
      "body": "First!"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "2" }
      }
    },
    "links": {
      "self": "http://example.com/comments/5"
    }
  }, {
    "type": "comments",
    "id": "12",
    "attributes": {
      "body": "I like XML better"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "9" }
      }
    },
    "links": {
      "self": "http://example.com/comments/12"
    }
  }]
}

JSON:API의 주요 규칙

HTTP 메소드

Content-Type

쿼리 파라미터 패밀리

/?page[offset]=0&page[limit]=10

URL 디자인

// 기본 리소스 경로
GET /articles
GET /articles/1

// 관계 데이터 직접 조회 경로
GET /articles/1/relationships/author

// 포함된 리소스 조회
GET /articles/1/author

// 중첩 관계
GET /articles/1/comments/2

에러 응답

{
  "errors": [
    {
      "status": "400",
      "title": "Invalid Attribute",
      "detail": "First name must contain at least three characters."
    }
  ]
}

• id: 에러 트래킹을 위한 오류 식별자

• links: 오류 연관 문서 링크

• status: HTTP 상태 코드

• code: 서버 내부에서 정의한 에러 코드

• title: 오류의 짧은 요약

• detail: 오류의 구체적인 설명

• source: 오류가 발생한 원인 위치

• meta: 추가적인 컨텍스트 데이터

페이네이션

{
	"links": {
    "self": "http://example.com/articles",
    "next": "http://example.com/articles?page[offset]=2",
    "last": "http://example.com/articles?page[offset]=10"
  }
 }

JSON:API의 장단점

장점

• 표준화된 응답 구조: 모든 API가 같은 형태를 가지므로, 클라이언트 구현이 쉽다.

• 불필요한 요청 감소: included 필드로 관련 데이터를 한 번에 전달할 수 있다.

• 관계형 데이터 표현이 용이: relationships를 통해 관계를 명확히 표현한다.

• 에러 처리 일관성: errors 포맷을 통해 구조화된 에러를 전달한다.

단점

• 구조가 복잡하다: 리소스 관계가 복잡하지 않은 간단한 API에는 과할 수 있다.

• 초기 설정 부담: 제시하는 표준에 맞춰 응답을 포맷팅 하기가 부담스러울 수 있다.

• 유연성 제한: 규칙을 모두 준수하며 커스텀 응답 구조를 만들기가 어려울 수 있다.

JSON:API 활용이 도움이 될 수 있는 상황

• 여러 종류의 클라이언트(웹, 모바일, API 클라이언트)가 동일 API를 사용하는 경우

• 관계형 데이터(예: 사용자 ↔ 게시글 ↔ 댓글)가 많은 경우

• 프론트엔드가 GraphQL처럼 관계형 요청을 많이 하는 경우