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 http.Transport to add those headers. See example/main.go for an example.

func NewClientUsingGet

func NewClientUsingGet(endpoint string, httpClient Doer) Client

NewClientUsingGet returns a Client which makes GET requests to the given endpoint suitable for most users who wish to make GET requests instead of POST.

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 http.Transport to add those headers. See example/main.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.

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.

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 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.