graphql

README

graphql

Low-level GraphQL client for Go.

• Simple, familiar API
• Respects context.Context timeouts and cancellation
• Build and execute any kind of GraphQL request
• Use strong Go types for response data
• Use variables and upload files
• Simple error handling

Installation

Make sure you have a working Go environment. To install graphql, simply run:

$ go get github.com/machinebox/graphql

Usage

import "context"

// create a client (safe to share across requests)
client := graphql.NewClient("https://machinebox.io/graphql")

// make a request
req := graphql.NewRequest(`
    query ($key: String!) {
        items (id:$key) {
            field1
            field2
            field3
        }
    }
`)

// set any variables
req.Var("key", "value")

// set header fields
req.Header.Set("Cache-Control", "no-cache")

// define a Context for the request
ctx := context.Background()

// run it and capture the response
var respData ResponseStruct
if err := client.Run(ctx, req, &respData); err != nil {
    log.Fatal(err)
}

File support via multipart form data

By default, the package will send a JSON body. To enable the sending of files, you can opt to use multipart form data instead using the UseMultipartForm option when you create your Client:

client := graphql.NewClient("https://machinebox.io/graphql", graphql.UseMultipartForm())

For more information, read the godoc package documentation or the blog post.

Thanks

Thanks to Chris Broadfoot for design help.

Documentation

Overview

Package graphql provides a low level GraphQL client.

// create a client (safe to share across requests)
client := graphql.NewClient("https://machinebox.io/graphql")

// make a request
req := graphql.NewRequest(`
    query ($key: String!) {
        items (id:$key) {
            field1
            field2
            field3
        }
    }
`)

// set any variables
req.Var("key", "value")

// run it and capture the response
var respData ResponseStruct
if err := client.Run(ctx, req, &respData); err != nil {
    log.Fatal(err)
}

Specify client

To specify your own http.Client, use the WithHTTPClient option:

httpclient := &http.Client{}
client := graphql.NewClient("https://machinebox.io/graphql", graphql.WithHTTPClient(httpclient))

Index

• type Client
  • func NewClient(endpoint string, opts ...ClientOption) *Client
  • func (c *Client) Run(ctx context.Context, req *Request, resp interface{}) error
• type ClientOption
  • func UseMultipartForm() ClientOption
  • func WithHTTPClient(httpclient *http.Client) ClientOption
• type GraphErr
  • func (e GraphErr) Error() string
• type Request
  • func NewRequest(q string) *Request
  • func (req *Request) File(fieldname, filename string, r io.Reader)
  • func (req *Request) Var(key string, value interface{})

Types

type Client

type Client struct {

	// Log is called with various debug information.
	// To log to standard out, use:
	//  client.Log = func(s string) { log.Println(s) }
	Log func(s string)
	// contains filtered or unexported fields
}

Client is a client for interacting with a GraphQL API.

func NewClient

func NewClient(endpoint string, opts ...ClientOption) *Client

NewClient makes a new Client capable of making GraphQL requests.

func (*Client) Run

func (c *Client) Run(ctx context.Context, req *Request, resp interface{}) error

Run executes the query and unmarshals the response from the data field into the response object. Pass in a nil response object to skip response parsing. If the request fails or the server returns an error, the first error will be returned.

type ClientOption

type ClientOption func(*Client)

ClientOption are functions that are passed into NewClient to modify the behaviour of the Client.

func UseMultipartForm

func UseMultipartForm() ClientOption

UseMultipartForm uses multipart/form-data and activates support for files.

func WithHTTPClient

func WithHTTPClient(httpclient *http.Client) ClientOption

WithHTTPClient specifies the underlying http.Client to use when making requests.

NewClient(endpoint, WithHTTPClient(specificHTTPClient))

type GraphErr

type GraphErr struct {
	Message    string                 `json:"message"`
	Extensions map[string]interface{} `json:"extensions"`
}

func (GraphErr) Error

func (e GraphErr) Error() string

type Request

type Request struct {

	// Header represent any request headers that will be set
	// when the request is made.
	Header http.Header
	// contains filtered or unexported fields
}

Request is a GraphQL request.

func NewRequest

func NewRequest(q string) *Request

NewRequest makes a new Request with the specified string.

func (*Request) File

func (req *Request) File(fieldname, filename string, r io.Reader)

File sets a file to upload. Files are only supported with a Client that was created with the UseMultipartForm option.

func (*Request) Var

func (req *Request) Var(key string, value interface{})

Var sets a variable.