graphql

Documentation

Index

• type Client
  • func NewClient(endpoint string, httpClient Doer) Client
  • func NewClientUsingGet(endpoint string, httpClient Doer) Client
• type Doer
• type NoMarshalJSON
  • func (NoMarshalJSON) MarshalJSON() ([]byte, error)
• type NoUnmarshalJSON
  • func (NoUnmarshalJSON) UnmarshalJSON(b []byte) error
• type Request
• type Response

Types

type Client

type Client interface {
	// MakeRequest must make a request to the client's GraphQL API.
	//
	// ctx is the context that should be used to make this request.  If context
	// is disabled in the genqlient settings, this will be set to
	// context.Background().
	//
	// req contains the data to be sent to the GraphQL server.  Typically GraphQL
	// APIs will expect it to simply be marshalled as JSON, but MakeRequest may
	// customize this.
	//
	// resp is the Response object into which the server's response will be
	// unmarshalled. Typically GraphQL APIs will return JSON which can be
	// unmarshalled directly into resp, but MakeRequest can customize it.
	// If the response contains an error, this must also be returned by
	// MakeRequest.  The field resp.Data will be prepopulated with a pointer
	// to an empty struct of the correct generated type (e.g. MyQueryResponse).
	MakeRequest(
		ctx context.Context,
		req *Request,
		resp *Response,
	) error
}

Client is the interface that the generated code calls into to actually make requests.

func NewClient

func NewClient(endpoint string, httpClient Doer) Client

NewClient returns a Client which makes requests to the given endpoint, suitable for most users.

The client makes POST requests to the given GraphQL endpoint using standard GraphQL HTTP-over-JSON transport. It will use the given http client, or http.DefaultClient if a nil client is passed.

The typical method of adding authentication headers is to wrap the client's Transport to add those headers. See example/caller.go for an example.

func NewClientUsingGet

func NewClientUsingGet(endpoint string, httpClient Doer) Client

NewClientUsingGet returns a Client which makes requests to the given endpoint, suitable for most users.

The client makes GET requests to the given GraphQL endpoint using a GET query, with the query, operation name and variables encoded as URL parameters. It will use the given http client, or http.DefaultClient if a nil client is passed.

The client does not support mutations, and will return an error if passed a request that attempts one.

The typical method of adding authentication headers is to wrap the client's Transport to add those headers. See example/caller.go for an example.

type Doer

type Doer interface {
	Do(*http.Request) (*http.Response, error)
}

Doer encapsulates the methods from *http.Client needed by Client. The methods should have behavior to match that of *http.Client (or mocks for the same).

type NoMarshalJSON

type NoMarshalJSON struct{}

NoMarshalJSON is intended for the use of genqlient's generated code only.

It is used to prevent a struct type from inheriting its embed's MarshalJSON method, so if we construct a type:

type T struct { E; NoMarshalJSON }

where E has an MarshalJSON method, T will not inherit it, per the Go selector rules: https://golang.org/ref/spec#Selectors.

func (NoMarshalJSON) MarshalJSON

func (NoMarshalJSON) MarshalJSON() ([]byte, error)

MarshalJSON should never be called; it exists only to prevent a sibling MarshalJSON method from being promoted.

type NoUnmarshalJSON

type NoUnmarshalJSON struct{}

NoUnmarshalJSON is intended for the use of genqlient's generated code only.

It is used to prevent a struct type from inheriting its embed's UnmarshalJSON method, so if we construct a type:

type T struct { E; NoUnmarshalJSON }

where E has an UnmarshalJSON method, T will not inherit it, per the Go selector rules: https://golang.org/ref/spec#Selectors.

func (NoUnmarshalJSON) UnmarshalJSON

func (NoUnmarshalJSON) UnmarshalJSON(b []byte) error

UnmarshalJSON should never be called; it exists only to prevent a sibling UnmarshalJSON method from being promoted.

type Request

type Request struct {
	// The literal string representing the GraphQL query, e.g.
	// `query myQuery { myField }`.
	Query string `json:"query"`
	// A JSON-marshalable value containing the variables to be sent
	// along with the query, or nil if there are none.
	Variables interface{} `json:"variables,omitempty"`
	// The GraphQL operation name. The server typically doesn't
	// require this unless there are multiple queries in the
	// document, but genqlient sets it unconditionally anyway.
	OpName string `json:"operationName"`
}

Request contains all the values required to build queries executed by the graphql.Client.

Typically, GraphQL APIs will accept a JSON payload of the form

{"query": "query myQuery { ... }", "variables": {...}}`

and Request marshals to this format. However, MakeRequest may marshal the data in some other way desired by the backend.

type Response

type Response struct {
	Data       interface{}            `json:"data"`
	Extensions map[string]interface{} `json:"extensions,omitempty"`
	Errors     gqlerror.List          `json:"errors,omitempty"`
}

Response that contains data returned by the GraphQL API.

Typically, GraphQL APIs will return a JSON payload of the form

{"data": {...}, "errors": {...}}

It may additionally contain a key named "extensions", that might hold GraphQL protocol extensions. Extensions and Errors are optional, depending on the values returned by the server.