Send a GraphQL query

GraphQL 엔드포인트에 쿼리와 변수를 담아 POST하는 레시피입니다. 하나의 요청으로 필요한 필드만 정확히 받아옵니다.

개요

GraphQL 엔드포인트에 쿼리와 변수를 담아 POST하는 레시피입니다. 하나의 요청으로 필요한 필드만 정확히 받아옵니다.

코드로 보기

curl -X POST https://api.example.com/graphql \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token>' \
  -d '{"query":"query($id:ID!){ user(id:$id){ name email } }","variables":{"id":"1"}}'
const res = await fetch('https://api.example.com/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer <token>'
  },
  body: JSON.stringify({
    query: `query($id: ID!) { user(id: $id) { name email } }`,
    variables: { id: '1' }
  })
});
const { data, errors } = await res.json();
if (errors) throw new Error(errors[0].message);
import requests

payload = {
    'query': 'query($id: ID!) { user(id: $id) { name email } }',
    'variables': {'id': '1'},
}
res = requests.post('https://api.example.com/graphql',
                    json=payload,
                    headers={'Authorization': 'Bearer <token>'})
result = res.json()  # {'data': {...}} or {'errors': [...]}

설명

GraphQL은 보통 단일 URL(`/graphql`)에 `Content-Type: application/json`으로 POST하며, 본문은 `{ "query": "...", "variables": { ... }, "operationName": "..." }` 형태의 JSON입니다. 값은 쿼리 문자열에 직접 끼워 넣지 말고 반드시 `variables`로 분리해 주입 위험을 피하고 캐싱·재사용을 쉽게 하세요.

가장 큰 함정: GraphQL은 필드 수준 오류가 있어도 HTTP 상태로 200을 반환하는 경우가 많습니다. 따라서 `res.ok`만 보면 안 되고, 응답 본문의 `errors` 배열을 반드시 검사해야 합니다. 실제 데이터는 `data` 아래에, 오류는 `errors` 아래에 부분적으로 함께 올 수 있습니다.

인증은 REST와 동일하게 `Authorization: Bearer` 헤더로 보냅니다. 조회에도 POST를 쓰는 것이 일반적이라 GET 캐싱 이점이 없으므로, 지속 쿼리(persisted queries)나 APQ, 응답 캐시 계층으로 성능을 보완합니다. 구독(subscription)은 보통 WebSocket이나 SSE로 별도 처리합니다.

관련 헤더

Content-TypeAuthorization

관련 상태코드

200OK400Bad Request401Unauthorized