GraphQL over HTTP 초안

GraphQL over HTTP Draft

GraphQL 요청의 HTTP 메서드와 응답 미디어 타입을 상호운용 가능한 규칙으로 정의합니다.

···
html
<div class="viz"><h3>GRAPHQL /graphql</h3><div class="row"><div class="box code" id="gql-request">GET query</div><span class="arrow">→</span><div class="box" id="gql-result">200<br>response+json</div></div><div class="muted" id="gql-note">query may use GET</div></div>
css
.viz{width:94%;height:88%;max-width:960px;padding:clamp(10px,2vmin,18px);border:1px solid var(--line);border-radius:14px;background:var(--surface);font:600 clamp(12px,1.35vw,16px)/1.35 var(--font-sans,system-ui,sans-serif);display:flex;flex-direction:column;gap:clamp(7px,1.8vmin,13px);overflow:hidden}.viz h3{margin:0;color:var(--accent);font:700 clamp(12px,1.35vw,16px)/1.2 var(--font-sans,system-ui,sans-serif);letter-spacing:.04em}.viz .row{display:flex;align-items:center;justify-content:center;gap:clamp(5px,1.4vmin,12px);flex:1;min-height:0}.viz .box{padding:clamp(5px,1.5vmin,12px);border:1px solid var(--line);border-radius:9px;background:var(--bg);text-align:center}.viz .muted{color:var(--muted)}.viz .accent{color:var(--accent)}.viz .code{font-family:ui-monospace,monospace}.viz .pill{padding:3px 7px;border:1px solid var(--line);border-radius:99px;white-space:nowrap}.viz .active{border-color:var(--accent);background:color-mix(in srgb,var(--accent) 12%,var(--surface))}.viz .arrow{color:var(--accent);font:700 18px ui-monospace,monospace}#gql-request{min-width:35%}#gql-result{min-width:38%;border-color:var(--accent)}#gql-result.bad{border-color:var(--accent-3);color:var(--accent-3)}
js
const cases=[['GET query','200<br>response+json','query may use GET',false],['GET mutation','405<br>method rejected','mutation must not use GET',true],['POST mutation','200<br>response+json','POST is required',false]];let n=0;function draw(){const c=cases[n];document.getElementById('gql-request').textContent=c[0];const out=document.getElementById('gql-result');out.innerHTML=c[1];out.classList.toggle('bad',c[3]);document.getElementById('gql-note').textContent=c[2];n=(n+1)%cases.length}draw();setInterval(draw,1300)

GraphQL 자체 명세는 전송 방식을 정하지 않습니다. GraphQL over HTTP 초안은 POST를 필수로 하고 GET을 선택 사항으로 두며, GET에는 query 연산만 허용합니다. 클라이언트는 application/graphql-response+json을 Accept에 넣고, 서버는 해당 응답 미디어 타입을 지원해야 합니다.

데모는 GET 질의와 POST 변형을 통과시키고 GET 변형을 거절합니다. 이 문서는 아직 Stage 2 초안이라 내용이 달라질 수 있으므로 현재 구현과 사용 중인 클라이언트의 호환성을 점검해야 합니다.

언제 쓰나

서로 다른 GraphQL 클라이언트와 서버 사이의 HTTP 동작을 맞출 때 참고합니다.

페이지로 열기 ↗