graphqlc

README

graphqlc

Low-level GraphQL client for Go. This project was forked from machinebox's repo and includes some breaking changes, so some assembly is required if you are migrating from there.

• 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
• (Coming soon!) Subscriptions

Installation

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

$ go get github.com/leonardacademy/graphqlc

Usage

import "context"

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

// make a request
req := graphqlc.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. When files are included, the package transparently uses multipart form data instead.

For more information, read the godoc package documentation

Thanks

Thanks to Machinebox for creating the initial plugin.

Documentation

Overview

Package graphqlc provides a low level GraphQL client.

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

// make a request
req := graphqlc.NewRequest(`
    query ($key: String!) {
        items (id:$key) {
            field1
            field2
            field3
        }
    }
`)
//(optional) set your own http client
client.HttpClient = http.DefaultClient
//(optional) 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)
}

Index

• type Client
  • func NewClient(endpoint string, opts ...ClientOption) *Client
  • func (c *Client) Run(req *Request) error
  • func (c *Client) RunCtx(ctx context.Context, req *Request) error
  • func (c *Client) RunCtxRet(ctx context.Context, req *Request, resp interface{}) error
  • func (c *Client) RunRet(req *Request, resp interface{}) error
  • func (c *Client) Subscribe(ctx context.Context, req *Request, notifications chan SubscriptionEvent)
• type ClientOption
• type File
• type Request
  • func NewRequest(q string) *Request
  • func (req *Request) File(fieldname, filename string, r io.Reader)
  • func (req *Request) Files() []File
  • func (req *Request) Query() string
  • func (req *Request) Var(key string, value interface{})
  • func (req *Request) Vars() map[string]interface{}
• type SubscriptionEvent

Types

type Client

type Client struct {
	//The graphql server endpoint.
	Endpoint string

	//net/http client used to make requests.
	HttpClient *http.Client

	// closeReq will close the request body immediately allowing for reuse of client
	CloseReq bool

	// 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)

	//Determines the default http request headers for graphql queries.
	//If your graphql request has headers that contradict these, the
	//graphql request headers will take precedence.
	http.Header
}

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(req *Request) error

func (*Client) RunCtx

func (c *Client) RunCtx(ctx context.Context, req *Request) error

func (*Client) RunCtxRet

func (c *Client) RunCtxRet(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. Pass in a channel for resp if the request a synchronization request in order to get updates. If the request fails or the server returns an error, the first error encountered will be returned.

func (*Client) RunRet

func (c *Client) RunRet(req *Request, resp interface{}) error

func (*Client) Subscribe

func (c *Client) Subscribe(ctx context.Context, req *Request, notifications chan SubscriptionEvent)

type ClientOption

type ClientOption func(*Client)

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

type File

type File struct {
	Field string
	Name  string
	R     io.Reader
}

File represents a file to upload.

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) Files

func (req *Request) Files() []File

Files gets the files in this request.

func (*Request) Query

func (req *Request) Query() string

Query gets the query string of this request.

func (*Request) Var

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

Var sets a variable.

func (*Request) Vars

func (req *Request) Vars() map[string]interface{}

Vars gets the variables for this Request.

type SubscriptionEvent

type SubscriptionEvent struct {
	Data []byte
	Err  error
}