gqlclient

README

gqlclient

A GraphQL client and code generator for Go.

Usage

gqlclient can be used as a thin GraphQL client, and can be augmented with code generation. See the GoDoc examples for direct usage.

GraphQL schema code generation

The code generator can parse a GraphQL schema and generate Go types. For instance, the following schema:

type Train {
	name: String!
	maxSpeed: Int!
	weight: Int!
	linesServed: [String!]!
}

and the following gqlclientgen invocation:

gqlclientgen -s schema.graphqls -o gql.go -n rail

will generate the following Go type:

type Train struct {
	Name string
	MaxSpeed int32
	Weight int32
	LinesServed []string
}

which can then be used in a GraphQL query:

op := gqlclient.NewOperation(`query {
	train(name: "Shinkansen E5") {
		name
		maxSpeed
		linesServed
	}
}`)

var data struct {
	Train rail.Train
}
if err := c.Execute(ctx, op, &data); err != nil {
	log.Fatal(err)
}
log.Print(data.Train)

GraphQL query code generation

The code generator can also parse a GraphQL query document and generate Go functions. For instance, the following query document:

query fetchTrain($name: String!) {
	train(name: $name) {
		maxSpeed
		linesServed
	}
}

and the following gqlclientgen invocation:

gqlclientgen -s schema.graphqls -q queries.graphql -o gql.go -n rail

will generate the following function:

func FetchTrain(client *gqlclient.Client, ctx context.Context, name string) (Train, error)

which can then be used to execute the query:

train, err := rail.FetchTrain(c, ctx, "Shinkansen E5")
if err != nil {
	log.Fatal(err)
}
log.Print(train)

GraphQL schema introspection

gqlclient also supports fetching GraphQL schemas through GraphQL introspection. For instance, the following gqlintrospect invocation will fetch the GraphQL schema of the https://example.com/query GraphQL endpoint:

gqlintrospect https://example.com/query > schema.graphqls

Contributing

Send patches on the mailing list. Discuss in #emersion on Libera Chat.

License

MIT

Documentation

Index

• type Client
  • func New(endpoint string, hc *http.Client) *Client
  • func (c *Client) Execute(ctx context.Context, op *Operation, data interface{}) error
• type Error
  • func (err *Error) Error() string
• type ErrorLocation
• type HTTPError
  • func (err *HTTPError) Error() string
  • func (err *HTTPError) Unwrap() error
• type Operation
  • func NewOperation(query string) *Operation
  • func (op *Operation) Var(k string, v interface{})
• type Time
  • func (t Time) MarshalJSON() ([]byte, error)
  • func (t *Time) UnmarshalJSON(b []byte) error
• type Upload
  • func (Upload) MarshalJSON() ([]byte, error)

Examples

• Client.Execute
• Client.Execute (Upload)
• Client.Execute (Vars)

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a GraphQL HTTP client.

func New

func New(endpoint string, hc *http.Client) *Client

New creates a new GraphQL client with the specified endpoint.

If hc is nil, http.DefaultClient is used.

func (*Client) Execute

func (c *Client) Execute(ctx context.Context, op *Operation, data interface{}) error

Execute sends the operation to the GraphQL server.

The data returned by the server will be decoded into the data argument.

Example

package main

import (
	"context"
	"log"

	"git.sr.ht/~emersion/gqlclient"
)

func main() {
	var ctx context.Context
	var c *gqlclient.Client

	op := gqlclient.NewOperation(`query {
		me {
			name
		}
	}`)

	var data struct {
		Me struct {
			Name string
		}
	}
	if err := c.Execute(ctx, op, &data); err != nil {
		log.Fatal(err)
	}

	log.Print(data)
}

Example (Upload)

package main

import (
	"context"
	"log"
	"strings"

	"git.sr.ht/~emersion/gqlclient"
)

func main() {
	var ctx context.Context
	var c *gqlclient.Client

	op := gqlclient.NewOperation(`mutation ($file: Upload!) {
		send(file: $file)
	}`)

	op.Var("file", gqlclient.Upload{
		Filename: "gopher.txt",
		MIMEType: "text/plain",
		Body:     strings.NewReader("Hello, 世界"),
	})

	if err := c.Execute(ctx, op, nil); err != nil {
		log.Fatal(err)
	}
}

Example (Vars)

package main

import (
	"context"
	"log"

	"git.sr.ht/~emersion/gqlclient"
)

func main() {
	var ctx context.Context
	var c *gqlclient.Client

	op := gqlclient.NewOperation(`query ($name: String!) {
		user(username: $name) {
			age
		}
	}`)

	op.Var("name", "emersion")

	var data struct {
		User struct {
			Age int
		}
	}
	if err := c.Execute(ctx, op, &data); err != nil {
		log.Fatal(err)
	}

	log.Print(data)
}

type Error

type Error struct {
	Message    string
	Locations  []ErrorLocation
	Path       []interface{}
	Extensions json.RawMessage
}

Error is a GraphQL error.

func (*Error) Error

func (err *Error) Error() string

type ErrorLocation

type ErrorLocation struct {
	Line, Column int
}

ErrorLocation describes an error location in a GraphQL document.

Line and column numbers start from 1.

type HTTPError

type HTTPError struct {
	StatusCode int
	// contains filtered or unexported fields
}

HTTPError is an HTTP response error.

func (*HTTPError) Error

func (err *HTTPError) Error() string

func (*HTTPError) Unwrap

func (err *HTTPError) Unwrap() error

type Operation

type Operation struct {
	// contains filtered or unexported fields
}

Operation describes a GraphQL operation.

An operation is a query with variables.

func NewOperation

func NewOperation(query string) *Operation

NewOperation creates a new GraphQL operation.

func (*Operation) Var

func (op *Operation) Var(k string, v interface{})

Var defines a new variable.

If the variable is already defined, Var panics.

type Time

type Time struct {
	time.Time
}

func (Time) MarshalJSON

func (t Time) MarshalJSON() ([]byte, error)

func (*Time) UnmarshalJSON

func (t *Time) UnmarshalJSON(b []byte) error

type Upload

type Upload struct {
	Filename string
	MIMEType string
	Body     io.Reader
}

Upload is a file upload.

See the GraphQL multipart request specification for details: https://github.com/jaydenseric/graphql-multipart-request-spec

func (Upload) MarshalJSON

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

MarshalJSON implements json.Marshaler.