README
¶
graphql
Package graphql provides a GraphQL client implementation.
Requires Go version 1.15 or later.
Usage
Construct a GraphQL client, specifying the GraphQL server URL. Then, you can use it to make GraphQL queries and mutations.
client := graphql.NewClient("https://example.com/graphql", nil)
// Use client...
Authentication
Servers have different ways of doing authentication.
If your target server supports OAuth2, pass an http.Client like so:
import "golang.org/x/oauth2"
func main() {
src := oauth2.StaticTokenSource(
&oauth2.Token{AccessToken: os.Getenv("GRAPHQL_TOKEN")},
)
httpClient := oauth2.NewClient(context.Background(), src)
client := graphql.NewClient("https://example.com/graphql", httpClient)
// Use client...
See https://golang.org/x/oauth2 for more information.
For all other forms of authentication, pass in a function to write your own http headers
func main() {
client := graphql.NewClient("https://example.com/graphql", nil, func(h http.Header) error {
h.Add("Authorization", fmt.Sprintf("Bearer %s", "insert-api-token-here"))
})
}
Simple Query
To make a GraphQL query, you need to define a corresponding Go type.
For example, to make the following GraphQL query:
query {
me {
name
}
}
You can define this variable:
var query struct {
Me struct {
Name graphql.String
}
}
Then call client.Query, passing a pointer to it:
err := client.Query(context.Background(), &query, nil)
if err != nil {
// Handle error.
}
fmt.Println(query.Me.Name)
// Output: Luke Skywalker
Arguments and Variables
Often, you'll want to specify arguments on some fields. You can use the graphql struct field tag for this.
For example, to make the following GraphQL query:
{
human(id: "1000") {
name
height(unit: METER)
}
}
You can define this variable:
var q struct {
Human struct {
Name graphql.String
Height graphql.Float `graphql:"height(unit: METER)"`
} `graphql:"human(id: \"1000\")"`
}
Then call client.Query:
err := client.Query(context.Background(), &q, nil)
if err != nil {
// Handle error.
}
fmt.Println(q.Human.Name)
fmt.Println(q.Human.Height)
// Output:
// Luke Skywalker
// 1.72
However, that'll only work if the arguments are constant and known in advance. Otherwise, you will need to make use of variables. Replace the constants in the struct field tag with variable names:
var q struct {
Human struct {
Name graphql.String
Height graphql.Float `graphql:"height(unit: $unit)"`
} `graphql:"human(id: $id)"`
}
Then, define a variables map with their values:
variables := map[string]interface{}{
"id": graphql.ID(id),
"unit": starwars.LengthUnit("METER"),
}
Finally, call client.Query providing variables:
err := client.Query(context.Background(), &q, variables)
if err != nil {
// Handle error.
}
Inline Fragments
Some GraphQL queries contain inline fragments. You can use the graphql struct field tag to express them.
For example, to make the following GraphQL query:
{
hero(episode: "JEDI") {
name
... on Droid {
primaryFunction
}
... on Human {
height
}
}
}
You can define this variable:
var q struct {
Hero struct {
Name graphql.String
Droid struct {
PrimaryFunction graphql.String
} `graphql:"... on Droid"`
Human struct {
Height graphql.Float
} `graphql:"... on Human"`
} `graphql:"hero(episode: \"JEDI\")"`
}
Alternatively, you can define the struct types corresponding to inline fragments, and use them as embedded fields in your query:
type (
DroidFragment struct {
PrimaryFunction graphql.String
}
HumanFragment struct {
Height graphql.Float
}
)
var q struct {
Hero struct {
Name graphql.String
DroidFragment `graphql:"... on Droid"`
HumanFragment `graphql:"... on Human"`
} `graphql:"hero(episode: \"JEDI\")"`
}
Then call client.Query:
err := client.Query(context.Background(), &q, nil)
if err != nil {
// Handle error.
}
fmt.Println(q.Hero.Name)
fmt.Println(q.Hero.PrimaryFunction)
fmt.Println(q.Hero.Height)
// Output:
// R2-D2
// Astromech
// 0
Mutations
Mutations often require information that you can only find out by performing a query first. Let's suppose you've already done that.
For example, to make the following GraphQL mutation:
mutation($ep: Episode!, $review: ReviewInput!) {
createReview(episode: $ep, review: $review) {
stars
commentary
}
}
variables {
"ep": "JEDI",
"review": {
"stars": 5,
"commentary": "This is a great movie!"
}
}
You can define:
var m struct {
CreateReview struct {
Stars graphql.Int
Commentary graphql.String
} `graphql:"createReview(episode: $ep, review: $review)"`
}
variables := map[string]interface{}{
"ep": starwars.Episode("JEDI"),
"review": starwars.ReviewInput{
Stars: graphql.Int(5),
Commentary: graphql.String("This is a great movie!"),
},
}
Then call client.Mutate:
err := client.Mutate(context.Background(), &m, variables)
if err != nil {
// Handle error.
}
fmt.Printf("Created a %v star review: %v\n", m.CreateReview.Stars, m.CreateReview.Commentary)
// Output:
// Created a 5 star review: This is a great movie!
Directories
| Path | Synopsis |
|---|---|
| example/graphqldev | graphqldev is a test program currently being used for developing graphql package. |
| ident | Package ident provides functions for parsing and converting identifier names between various naming convention. |
| internal/jsonutil | Package jsonutil provides a function for decoding JSON into a GraphQL query data structure. |
License
Documentation
¶
Overview ¶
Package graphql provides a GraphQL client implementation.
For more information, see package github.com/shurcooL/githubv4, which is a specialized version targeting GitHub GraphQL API v4. That package is driving the feature development.
For now, see README for more details.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Boolean ¶
type Boolean bool
Boolean represents true or false values.
func NewBoolean ¶
NewBoolean is a helper to make a new *Boolean.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a GraphQL client.
func NewClient ¶
NewClient creates a GraphQL client targeting the specified GraphQL server URL. If httpClient is nil, then http.DefaultClient is used.
func NewClientWithHeaders ¶
func NewClientWithHeaders(url string, httpClient *http.Client, headersFunc WriteHeadersFunc) *Client
NewClientWithHeaders creates a GraphQL client that allows overriding headers
func (*Client) Mutate ¶
Mutate executes a single GraphQL mutation request, with a mutation derived from m, populating the response into it. m should be a pointer to struct that corresponds to the GraphQL schema.
type Float ¶
type Float float64
Float represents signed double-precision fractional values as specified by IEEE 754.
type ID ¶
type ID interface{}
ID represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "VXNlci0xMA==") or integer (such as 4) input value will be accepted as an ID.
type Int ¶
type Int int32
Int represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.
type String ¶
type String string
String represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.
type WriteHeadersFunc ¶
WriteHeadersFunc is a function signature that writes headers.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
example
|
|
|
graphqldev
graphqldev is a test program currently being used for developing graphql package.
|
graphqldev is a test program currently being used for developing graphql package. |
|
Package ident provides functions for parsing and converting identifier names between various naming convention.
|
Package ident provides functions for parsing and converting identifier names between various naming convention. |
|
internal
|
|
|
jsonutil
Package jsonutil provides a function for decoding JSON into a GraphQL query data structure.
|
Package jsonutil provides a function for decoding JSON into a GraphQL query data structure. |