GraphQL
Call a GraphQL endpoint with variables, pick data, and treat a 200 carrying errors as a failure.
Use graphql() when an API speaks GraphQL-over-HTTP and you want a stitch that
POSTs a query, passes variables per call, and hands back the data payload
already picked — with a 200 that carries an errors array treated as a
failure, not a success.
Example
import { } from 'stitchapi';
const = <{ : { : string; : string } }>({
: 'https://api.example.com',
: '/graphql',
: `query GetUser($id: ID!) { user(id: $id) { id name } }`,
});
// Variables travel in the input; the result is already picked from `data`.
const = await ({ : { : '1' } });Options
graphql() is a thin wrapper over stitch(): it fixes kind: 'graphql',
method: 'POST', and pick: 'data' for you. You supply the GraphQL document
as document, plus a baseUrl/path pointing at the endpoint.
document and operationName are read only by the graphql surface, so
they are a type error on any other one — a plain stitch({ document })
would otherwise drop the document silently and send an ordinary request.
Reach for graphql() (or seam.graphql()), which selects the surface for
you; the generic spelling works too if you name it yourself:
import { graphqlSurface, stitch } from 'stitchapi';
stitch({ baseUrl, kind: graphqlSurface, document: `query { me { id } }` });The check reads the config you write, not the composed result — so a
surface inherited through extends is not seen. Put kind on the same
layer as the document, or use graphql().
Pass GraphQL variables through the input's variables field at call time —
getUser({ variables: { id: '1' } }) — so one stitch serves every set of
arguments. Because pick defaults to 'data', the resolved value is the
contents of the response's data object; override pick if you need a
different field or the raw envelope.
Anti-pattern: don't interpolate argument values straight into the
query string and mint a fresh stitch for each set of arguments; pass them
through the input's variables field at call time so one declared stitch
serves every call. See Reference → stitch.
A GraphQL endpoint can return HTTP 200 while reporting an errors array
in the body. The stitch treats that as a failure and surfaces it — see
STITCH_GRAPHQL.
File uploads are not supported
The surface builds the request body itself, so wire.body is not a field a
GraphQL stitch accepts — authoring one is a compile error rather than a silently
ignored setting. Its siblings are unaffected: wire.response and wire.array
are not body encodings, so both stay legal here.
That includes wire: { body: 'multipart' }. A GraphQL file upload is not "the
JSON body, multipart-encoded" — it is a distinct wire format, the GraphQL
multipart request
spec, which
frames the call as an operations part, a map part, and one part per file.
This surface does not implement that envelope. Until it does, upload the file
with a plain stitch() using
wire: { body: 'multipart' } and pass the returned identifier as a GraphQL
variable —
which is also what Apollo's own upload
guidance
recommends over in-band multipart uploads.
For the full set of fields a stitch accepts, see Reference → Config types.