🔙뒤로가기

GraphQL에서는 하나의 엔드포인트를 통해 클라이언트의 요청을 처리한다. 이 때, 요청과 응답의 형태는 아래와 같다.

요청 구조

GraphQL 요청은 HTTP POST 메서드를 통해 보내진다. 요청의 본문은 JSON 형태이며, 다음 세 가지 요소로 구성되어 있다.

1. query : 필수 요소로, 서버에게 보낼 GraphQL 쿼리나 뮤테이션이다.

2. variables : 선택 요소로, 쿼리에 전달될 변수들이다.

3. operationname : 선택 요소로, 실행할 쿼리나 뮤테이션의 이름이다. 한 요청에 여러 개의 쿼리나 뮤테이션이 존재할 때 구분지을 수 있다.

   <aside> 💡 왜 subscription은 query에 포함되지 않는가? subscription은 실시간 업데이트를 수신하기 위해 사용되며, 클라이언트가 subscription을 정의하면 서버는 해당 이벤트가 발생할 때마다 업데이트를 클라이언트에게 푸시한다.

   이는 일반적으로 웹소켓 같은 실시간 통신 기술을 이용하여 구현되며, subscription의 정의와 사용은 query나 mutation과 유사하다. 그러나 subscription은 일반적으로 HTTP 요청/응답 모델이 아닌 실시간 연결을 통해 작동하므로, HTTP 요청 본문의 일부로 전송되는 것이 아니라 별도의 연결을 통해 설정되고 사용된다.

   따라서, HTTP 요청/응답 구조의 일부인 query 필드에 포함되지 않는다. 대신, 클라이언트는 별도의 웹소켓 연결을 통해 서버에 subscription을 설정하고, 서버는 해당 연결을 통해 실시간 업데이트를 푸시한다.

   </aside>

예를 들어, 사용자 정보를 가져오는 쿼리의 요청 본문은 아래와 같다.

{
  "query": "
    query GetUser($id: String) { 
      user(id: $id) { 
        name 
        email 
      } 
    }
    mutation UpdateUser($id: String, $email: String) {
      updateUser(id: $id, email: $email) {
        id
        email
      }
    }
  ",
  "variables": { "id": "1", "email": "[email protected]" },
  "operationName": "GetUser"
}

응답 구조

GraphQL 응답은 HTTP 응답의 본문을 통해 전달되며, JSON 형태로 반환된다. 응답은 다음 두 가지 요소로 구성된다.

1. data : 요청한 쿼리나 뮤테이션의 결과가 이 속성에 포함된다.
2. errors : 쿼리나 뮤테이션을 처리하는 동안 발생한 오류들이 이 속성에 포함된다.

위에서 사용한 쿼리에 대한 응답 본문.

{
  "data": {
    "user": {
      "name": "John",
      "email": "[email protected]"
    }
  }
}

존재하지 않는 사용자의 정보를 요청하는 쿼리에 대한 응답.

{
  "errors": [
    {
      "message": "User with id '2' not found.",
      "locations": [
        {
          "line": 1,
          "column": 2
        }
      ],
      "path": ["user"]
    }
  ],
  "data": {
    "user": null
  }
}