To install this package, run in Emacs:
M-x package-install RET graphql RET
GraphQL.el provides a set of generic functions for interacting with GraphQL web services.
See also the following resources:
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.
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.
Multiple edges can of course be followed. Here's an example using GitHub's API:
(graphql-query
((viewer login)
(rateLimit limit cost remaining resetAt)))
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
}
)
}
graphql-simplify-response-edges
Simplify structures like
(field (edges ((node node1values...)) ((node node2values...))))
into (field (node1values) (node2values))
.
: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.
:as
keyword for aliases (graphql-encode
).
...
qualifier for fragments and inline
fragments (graphql--encode-object
)
graphql-0.1.2.0.20221128.50646.tar.lz | 2022-Nov-28 | 5.93 KiB |
graphql-0.1.1.0.20221029.130854.tar.lz | 2022-Oct-29 | 5.88 KiB |