#graphql API reference

A thin GraphQL client over http / rest. Point a graphql.Client at one endpoint URL, then graphql.query(client, query, variables) POSTs {"query": ..., "variables": ...} and returns the decoded JSON response as a json.Value (the result is under /data).

The query is an opaque string the caller supplies - GraphQL syntax is the server's job, not this module's - and a mutation is just a query string, so no separate verb is needed. The one GraphQL-specific rule this client gets right: a GraphQL execution error is an HTTP 200 with a top-level errors array, not a non-2xx status, so query inspects the payload and raises a positioned Error (kind "graphql") carrying the server's messages rather than trusting the status line. A genuine transport / auth failure (a non-2xx status) is also raised as a graphql error with the status and body.

For a document that defines several named operations, queryNamed / tryQueryNamed add the operationName selector. To handle GraphQL errors yourself instead of catching a throw - branching on an error code, reading partial data - tryQuery / tryQueryNamed return the raw envelope (both /data and /errors) and only raise on an HTTP-level failure; graphql.hasErrors and graphql.errorMessages inspect it.

The Client wraps a rest.Client, so it carries the endpoint URL, per-request headers, and (via rest's http.TlsOptions) TLS settings for a self-signed or private-CA host. Default jennifer binary only (net-backed via http / rest).

Import with import "graphql.j" as graphql;. See the graphql guide for prose and examples.

#Functions

#graphql.basic(c as Client, user as string, pass as string)

Return a copy of the client that sends HTTP Basic Authorization.

Parameters

• c {Client} - the client
• user {string} - the username
• pass {string} - the password

Returns {Client} - a new client with the header set

#graphql.bearer(c as Client, token as string)

Return a copy of the client that sends Authorization: Bearer <token>.

Parameters

• c {Client} - the client
• token {string} - the bearer token

Returns {Client} - a new client with the header set

#graphql.client(endpoint as string)

A GraphQL client for one endpoint URL. The full endpoint is POSTed to verbatim (no path is appended), so pass the complete GraphQL URL (e.g. https://host/graphql).

Parameters

• endpoint {string} - the GraphQL endpoint URL

Returns {Client} - a client with no auth and default (verifying) TLS

#graphql.errorMessages(resp as json.Value)

Join the message field of each entry in a response's errors array into one "; "-separated string (this is the text query puts in the raised Error). For structured error data - extensions.code, path, locations - read the errors array of the envelope directly with the json accessors, e.g. json.asString($resp, "/errors/0/extensions/code").

Parameters

• resp {json.Value} - a decoded GraphQL response with an errors array

Returns {string} - the joined error messages

#graphql.hasErrors(resp as json.Value)

Report whether a decoded response carries a non-empty top-level errors array - the GraphQL error signal, which the spec delivers on an HTTP 200. Use this on the envelope returned by tryQuery to branch without a try / catch.

Parameters

• resp {json.Value} - a decoded GraphQL response

Returns {bool} - true if the response reports one or more GraphQL errors

#graphql.header(c as Client, name as string, value as string)

Return a copy of the client with an arbitrary request header set.

Parameters

• c {Client} - the client
• name {string} - the header name
• value {string} - the header value

Returns {Client} - a new client with the header set

#graphql.insecure(c as Client)

Return a copy of the client that skips TLS certificate verification. Insecure - for a trusted network or a local test server only.

Parameters

• c {Client} - the client

Returns {Client} - a new client that accepts any server certificate

#graphql.query(c as Client, query as string, variables as json.Value)

Run a GraphQL operation (query or mutation) and return the decoded JSON response as a json.Value; the result is at /data. The variables is a json.Value object (use an empty json.map() when the operation takes none).

Raises a positioned Error (kind "graphql") when the server reports GraphQL execution errors (an HTTP 200 with a top-level errors array - the messages are collected into the error), or when the request fails at the HTTP level (a non-2xx status, carrying the status and body). A successful return therefore has no errors, so /data is present and complete. To handle GraphQL errors yourself (e.g. branch on an error code), use tryQuery.

Parameters

• c {Client} - the client
• query {string} - the GraphQL query or mutation document
• variables {json.Value} - the variables object (empty object for none)

Returns {json.Value} - the full decoded response (data under /data)

Throws

• {Error} - kind "graphql" on GraphQL errors or a non-2xx HTTP status

#graphql.queryNamed(c as Client, query as string, variables as json.Value, operationName as string)

Like query, but for a document that defines several named operations: the operationName selects which one to run (some servers require it when more than one is present).

Parameters

• c {Client} - the client
• query {string} - the GraphQL document
• variables {json.Value} - the variables object (empty object for none)
• operationName {string} - the name of the operation to execute

Returns {json.Value} - the full decoded response (data under /data)

Throws

• {Error} - kind "graphql" on GraphQL errors or a non-2xx HTTP status

#graphql.tryQuery(c as Client, query as string, variables as json.Value)

Run an operation and return the decoded response without raising on GraphQL errors - the envelope comes back with both /data (possibly partial) and /errors, so you can inspect the errors yourself (graphql.hasErrors($resp), graphql.errorMessages($resp), or json.asString($resp, "/errors/0/extensions/code") for structured data). An HTTP-level failure (a non-2xx status) still raises, since there is no GraphQL envelope to return.

Parameters

• c {Client} - the client
• query {string} - the GraphQL query or mutation document
• variables {json.Value} - the variables object (empty object for none)

Returns {json.Value} - the full decoded response (data under /data, errors under /errors)

Throws

• {Error} - kind "graphql" only on a non-2xx HTTP status

#graphql.tryQueryNamed(c as Client, query as string, variables as json.Value, operationName as string)

tryQuery (no raise on GraphQL errors) for a document with several named operations, selected by operationName.

Parameters

• c {Client} - the client
• query {string} - the GraphQL document
• variables {json.Value} - the variables object (empty object for none)
• operationName {string} - the name of the operation to execute

Returns {json.Value} - the full decoded response (data under /data, errors under /errors)

Throws

• {Error} - kind "graphql" only on a non-2xx HTTP status

#graphql.withCA(c as Client, pem as bytes)

Return a copy of the client that trusts a private-CA / self-signed certificate (PEM). Certificate verification stays on, against this CA.

Parameters

• c {Client} - the client
• pem {bytes} - the CA certificate in PEM form

Returns {Client} - a new client with the CA trusted

#Structs

#graphql.Client

A GraphQL client: an endpoint URL plus headers and TLS options, carried in a wrapped rest.Client. Build one with graphql.client, then layer auth / TLS with the builders (each returns a new Client; value semantics, no mutation).