aboutsummaryrefslogtreecommitdiffstats
path: root/vendor/github.com/shurcooL/graphql/README.md
diff options
context:
space:
mode:
authorMichael Muré <batolettre@gmail.com>2018-09-24 19:22:32 +0200
committerMichael Muré <batolettre@gmail.com>2018-09-24 19:22:32 +0200
commitc4a207622a894ba9839f1a3c47c9d78beff9b861 (patch)
tree009d80b363b5392e6eba4bec85b0ae74b3942995 /vendor/github.com/shurcooL/graphql/README.md
parentc86e7231b223d532e26ab5449715c65b6b4e3fde (diff)
downloadgit-bug-c4a207622a894ba9839f1a3c47c9d78beff9b861.tar.gz
github: query most of the data
Diffstat (limited to 'vendor/github.com/shurcooL/graphql/README.md')
-rw-r--r--vendor/github.com/shurcooL/graphql/README.md293
1 files changed, 293 insertions, 0 deletions
diff --git a/vendor/github.com/shurcooL/graphql/README.md b/vendor/github.com/shurcooL/graphql/README.md
new file mode 100644
index 00000000..6fa03bd4
--- /dev/null
+++ b/vendor/github.com/shurcooL/graphql/README.md
@@ -0,0 +1,293 @@
+graphql
+=======
+
+[![Build Status](https://travis-ci.org/shurcooL/graphql.svg?branch=master)](https://travis-ci.org/shurcooL/graphql) [![GoDoc](https://godoc.org/github.com/shurcooL/graphql?status.svg)](https://godoc.org/github.com/shurcooL/graphql)
+
+Package `graphql` provides a GraphQL client implementation.
+
+For more information, see package [`github.com/shurcooL/githubv4`](https://github.com/shurcooL/githubv4), which is a specialized version targeting GitHub GraphQL API v4. That package is driving the feature development.
+
+**Status:** In active early research and development. The API will change when opportunities for improvement are discovered; it is not yet frozen.
+
+Installation
+------------
+
+`graphql` requires Go version 1.8 or later.
+
+```bash
+go get -u github.com/shurcooL/graphql
+```
+
+Usage
+-----
+
+Construct a GraphQL client, specifying the GraphQL server URL. Then, you can use it to make GraphQL queries and mutations.
+
+```Go
+client := graphql.NewClient("https://example.com/graphql", nil)
+// Use client...
+```
+
+### Authentication
+
+Some GraphQL servers may require authentication. The `graphql` package does not directly handle authentication. Instead, when creating a new client, you're expected to pass an `http.Client` that performs authentication. The easiest and recommended way to do this is to use the [`golang.org/x/oauth2`](https://golang.org/x/oauth2) package. You'll need an OAuth token with the right scopes. Then:
+
+```Go
+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...
+```
+
+### Simple Query
+
+To make a GraphQL query, you need to define a corresponding Go type.
+
+For example, to make the following GraphQL query:
+
+```GraphQL
+query {
+ me {
+ name
+ }
+}
+```
+
+You can define this variable:
+
+```Go
+var query struct {
+ Me struct {
+ Name graphql.String
+ }
+}
+```
+
+Then call `client.Query`, passing a pointer to it:
+
+```Go
+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:
+
+```GraphQL
+{
+ human(id: "1000") {
+ name
+ height(unit: METER)
+ }
+}
+```
+
+You can define this variable:
+
+```Go
+var q struct {
+ Human struct {
+ Name graphql.String
+ Height graphql.Float `graphql:"height(unit: METER)"`
+ } `graphql:"human(id: \"1000\")"`
+}
+```
+
+Then call `client.Query`:
+
+```Go
+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:
+
+```Go
+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:
+
+```Go
+variables := map[string]interface{}{
+ "id": graphql.ID(id),
+ "unit": starwars.LengthUnit("METER"),
+}
+```
+
+Finally, call `client.Query` providing `variables`:
+
+```Go
+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:
+
+```GraphQL
+{
+ hero(episode: "JEDI") {
+ name
+ ... on Droid {
+ primaryFunction
+ }
+ ... on Human {
+ height
+ }
+ }
+}
+```
+
+You can define this variable:
+
+```Go
+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:
+
+```Go
+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`:
+
+```Go
+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:
+
+```GraphQL
+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:
+
+```Go
+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`:
+
+```Go
+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](https://godoc.org/github.com/shurcooL/graphql/example/graphqldev) | graphqldev is a test program currently being used for developing graphql package. |
+| [ident](https://godoc.org/github.com/shurcooL/graphql/ident) | Package ident provides functions for parsing and converting identifier names between various naming convention. |
+| [internal/jsonutil](https://godoc.org/github.com/shurcooL/graphql/internal/jsonutil) | Package jsonutil provides a function for decoding JSON into a GraphQL query data structure. |
+
+License
+-------
+
+- [MIT License](LICENSE)