GraphQL best practice

Gzip

GraphQL 서비스는 일반적으로 JSON으로 응답하지만 GraphQL 명세에서는 필수는 아니다.  JSON은 더 좋은 네트워크 성능을 보장하는 API 레이어를 위해서는 이상한 선택처럼 보일 수 있지만 대부분 텍스트이기 때문에 GZIP으로 매우 잘 압축된다. 모든 프로덕션 GraphQL 서비스는 GZIP을 활성화하고 클라이언트가 다음 헤더를 보내는것을 권장한다.

Accept-Encoding: gzip

 

버저닝

API 엔드포인트에서 리턴된 데이터에 대한 변경이 있을 때 모든 변경은 큰 변화를 일으킬 수 있으며, 큰 변경사항에는 새 버전이 필요하다. GraphQL은 명시적으로 요청된 데이터만 반환하므로 새로운 타입과 필드를 통해 새로운 기능을 추가할 수 있고, 버저닝에서 큰 강점을 갖는다.

 

HTTP Methods, Headers, and Body

GraphQL HTTP 서버는 HTTP GET, POST 메서드를 처리해야한다.

 

GET request

HTTP GET 요청을 수신하면, GraphQL 요청을 query 쿼리스트링에 지정해야합니다. 예를 들어, 다음 GraphQL 쿼리를 실행하고자 한다면,

{
  me {
    name
  }
}

이 요청은 다음과 같이 HTTP GET을 통해 전송될 수 있다.

http://myapi/graphql?query={me{name}}

POST request

표준 GraphQL POST 요청은 application/json content-type을 사용해야하며 아래 형식의 JSON 인코딩 바디을 포함해야한다.

{
  "query": "...",
  "operationName": "...",
  "variables": { "myVariable": "someValue", ... }
}

application/graphql Content-Type header가 있는 경우 HTTP POST body 내용을 GraphQL 쿼리스트링으로 처리한다.

 

Response

{
  "data": { ... },
  "errors": [ ... ]
}

오류가 없는 경우 응답에 "errors" 필드가 없어야한다.

"data" 필드는 실행 중 에러가 발생했을 때만 포함되어야한다.