GraphQL utilities
Clone or download
Latest commit e2b3096 Sep 15, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Do not suggest packaging `examples.el' Sep 12, 2018
test Fix version check Sep 12, 2018
.gitignore Use new version of Emake Sep 15, 2018
.travis.yml Use new version of Emake Sep 15, 2018
Makefile Add 'clean' target Sep 15, 2018
README.md Add badges Sep 12, 2018
graphql.el Release version 0.1.1 Sep 12, 2018

README.md

GraphQL.el

MELPA Status Build Status

GraphQL.el provides a set of generic functions for interacting with GraphQL web services.

See also the following resources:

Syntax Overview

Two macros are provided to express GraphQL queries and mutations:

  • graphql-query encodes the graph provided under a root (query ...) node.
  • graphql-mutation encodes the graph provided under a root (mutation ...) node. Both macros allow special syntax for query/mutation parameters if this is desired; see the docstrings for details. I will note that backtick notation usually feels more natural in Lisp code.

Basic Queries

The body of these macros is the graph of your query/mutation expressed in a Lispy DSL. Generally speaking, we represent fields as symbols and edges as nested lists with the edge name being the head of that list. For example,

(graphql-query
 (myField1 myField2 (myEdges (edges (node myField3)))))

will construct a query that retrieves myField1, myField2, and myField3 for every node in myEdges. The query is returned as a string without any unnecessary whitespace (i.e., formatting) added.

Following Edges

Multiple edges can of course be followed. Here's an example using GitHub's API:

(graphql-query
 ((viewer login)
  (rateLimit limit cost remaining resetAt)))

Passing Arguments

Usually, queries need explicit arguments. We pass them in an alist set off by the :arguments keyword:

(graphql-query
 ((repository
   :arguments ((owner . "github")
               (name . ($ repo)))
   (issues :arguments ((first . 20)
                       (states . [OPEN CLOSED]))
           (edges
            (node number title url id))))))

As you can see, strings, numbers, vectors, symbols, and variables can all be given as arguments. The above evaluates to the following (formatting added):

query {
  repository (owner: "github", name: $repo) {
    issues (first: 20, states: [OPEN, CLOSED]) {
      edges {
        node {
          number title url id
        }
      }
    }
  }
}

Objects as arguments work, too, though practical examples seem harder to come by:

(graphql-query
 ((object :arguments ((someVariable . ((someComplex . "object")
                                       (with . ($ complexNeeds))))))))

gives

query {
  object (
    someVariable: {
      someComplex: "object",
      with: $complexNeeds
    }
  )
}

Working with Responses

  • graphql-simplify-response-edges Simplify structures like

    (field
     (edges
      ((node node1values...))
      ((node node2values...))))
    

    into (field (node1values) (node2values)).

Keyword Reference

  • :arguments Pass arguments to fields as an alist of parameters (as symbols) to values. See graphql--encode-argument-value.
  • :op-name, :op-params Operation name/parameters. Given to top-level query or mutation operations for later re-use. You should rarely (if ever) need to supply these yourself; the graphql-query and graphql-mutation macros give you natural syntax to do this.

Planned