# GRAPHQL HTTP Transport

> Serve GraphQL over HTTP with a single endpoint, POST/GET contracts, correct media types, partial 2xx responses, and auth middleware ordering. Use when wiring GraphQL servers or debugging transport mismatches.

- Skill: `deangrant/graphql-http-transport` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add deangrant/graphql-http-transport`
- Raw SKILL.md: https://api.skillmd.com/api/skills/deangrant/graphql-http-transport/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: deangrant (https://skillmd.com/u/deangrant)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/deangrant/graphql-http-transport

---


# GraphQL HTTP Transport

Use this skill when configuring **how GraphQL rides on HTTP**.

---

## 1. Endpoint and middleware

Single URL (e.g. `/graphql`). Authenticate in HTTP middleware **before** GraphQL
validation. Authorization during field execution. Allow partial responses.

---

## 2. Request contract

- **POST** required for queries + mutations (`Content-Type: application/json`).
- **GET** optional for queries only.
- Body: `query` required; `operationName` if multiple ops; optional `variables`,
  `extensions`.
- Client `Accept`: `application/graphql-response+json` (+ legacy JSON).

---

## 3. Response contract

`Content-Type: application/graphql-response+json` (or legacy JSON). Body
`{ data, errors?, extensions? }`. Pre-execution failure: `errors` only.
Non-null `data` + field errors → **2xx**.

Modern media type may use 4xx/5xx when execution cannot start; legacy often
returns 2xx + errors — clients must parse `errors`, not status alone.

---

## 4. Caching (optional)

GET + persisted query IDs for CDN. Cache key = persisted ID + variables.

---

## 5. Quick checklist

- [ ] Single endpoint; auth before validation.
- [ ] POST JSON contract documented.
- [ ] Correct Content-Type / Accept.
- [ ] Partial success = 2xx when data present.
- [ ] Clients triage via `errors` array.

See [reference.md](reference.md) and [examples.md](examples.md).