1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="generator" content="pandoc">
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
<title>GraphQL Haskell Tutorial</title>
<style type="text/css">code{white-space: pre;}</style>
<style type="text/css">
div.sourceCode { overflow-x: auto; }
table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode {
margin: 0; padding: 0; vertical-align: baseline; border: none; }
table.sourceCode { width: 100%; line-height: 100%; }
td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; }
td.sourceCode { padding-left: 5px; }
code > span.kw { color: #0000ff; } /* Keyword */
code > span.ch { color: #008080; } /* Char */
code > span.st { color: #008080; } /* String */
code > span.co { color: #008000; } /* Comment */
code > span.ot { color: #ff4000; } /* Other */
code > span.al { color: #ff0000; } /* Alert */
code > span.er { color: #ff0000; font-weight: bold; } /* Error */
code > span.wa { color: #008000; font-weight: bold; } /* Warning */
code > span.cn { } /* Constant */
code > span.sc { color: #008080; } /* SpecialChar */
code > span.vs { color: #008080; } /* VerbatimString */
code > span.ss { color: #008080; } /* SpecialString */
code > span.im { } /* Import */
code > span.va { } /* Variable */
code > span.cf { color: #0000ff; } /* ControlFlow */
code > span.op { } /* Operator */
code > span.bu { } /* BuiltIn */
code > span.ex { } /* Extension */
code > span.pp { color: #ff4000; } /* Preprocessor */
code > span.do { color: #008000; } /* Documentation */
code > span.an { color: #008000; } /* Annotation */
code > span.cv { color: #008000; } /* CommentVar */
code > span.at { } /* Attribute */
code > span.in { color: #008000; } /* Information */
</style>
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css">
<link rel="stylesheet" href="tutorial.css">
<!--[if lt IE 9]>
<script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
<![endif]-->
</head>
<body>
<header>
<h1 class="title">GraphQL Haskell Tutorial</h1>
</header>
<nav id="TOC">
<ul>
<li><a href="#getting-started">Getting started</a><ul>
<li><a href="#first-example">First example</a></li>
<li><a href="#monadic-actions">Monadic actions</a></li>
<li><a href="#errors">Errors</a></li>
<li><a href="#combining-resolvers">Combining resolvers</a></li>
</ul></li>
<li><a href="#further-examples">Further examples</a></li>
</ul>
</nav>
<section id="getting-started" class="level2">
<h2>Getting started</h2>
<p>Welcome to graphql-haskell!</p>
<p>We have written a small tutorial to help you (and ourselves) understand the graphql package.</p>
<p>Since this file is a literate haskell file, we start by importing some dependencies.</p>
<div class="sourceCode"><pre class="sourceCode literate haskell"><code class="sourceCode haskell"><span class="ot">{-# LANGUAGE OverloadedStrings #-}</span>
<span class="ot">{-# LANGUAGE LambdaCase #-}</span>
<span class="kw">module</span> <span class="dt">Main</span> <span class="kw">where</span>
<span class="kw">import </span><span class="dt">Prelude</span> <span class="kw">hiding</span> (empty, putStrLn)
<span class="kw">import </span><span class="dt">Data.GraphQL</span>
<span class="kw">import </span><span class="dt">Data.GraphQL.Schema</span>
<span class="kw">import qualified</span> <span class="dt">Data.GraphQL.Schema</span> <span class="kw">as</span> <span class="dt">Schema</span>
<span class="kw">import </span><span class="dt">Control.Applicative</span>
<span class="kw">import </span><span class="dt">Data.Text</span> <span class="kw">hiding</span> (empty)
<span class="kw">import </span><span class="dt">Data.Aeson</span>
<span class="kw">import </span><span class="dt">Data.ByteString.Lazy.Char8</span> (putStrLn)
<span class="kw">import </span><span class="dt">Data.Time</span>
<span class="kw">import </span><span class="dt">Debug.Trace</span></code></pre></div>
<section id="first-example" class="level3">
<h3>First example</h3>
<p>Now, as our first example, we are going to look at the example from <a href="https://github.com/graphql/graphql-js">graphql.js</a>.</p>
<p>First we build a GraphQL schema.</p>
<div class="sourceCode"><pre class="sourceCode literate haskell"><code class="sourceCode haskell"><span class="ot">schema1 ::</span> <span class="dt">Alternative</span> f <span class="ot">=></span> <span class="dt">Schema</span> f
schema1 <span class="fu">=</span> <span class="dt">Schema</span> [hello]
<span class="ot">hello ::</span> <span class="dt">Alternative</span> f <span class="ot">=></span> <span class="dt">Resolver</span> f
hello <span class="fu">=</span> Schema.scalar <span class="st">"hello"</span> (<span class="st">"it's me"</span><span class="ot"> ::</span> <span class="dt">Text</span>)</code></pre></div>
<p>This defines a simple schema with one type and one field, that resolves to a fixed value.</p>
<p>Next we define our query.</p>
<div class="sourceCode"><pre class="sourceCode literate haskell"><code class="sourceCode haskell"><span class="ot">query1 ::</span> <span class="dt">Text</span>
query1 <span class="fu">=</span> <span class="st">"{ hello }"</span></code></pre></div>
<p>To run the query, we call the <code>graphql</code> with the schema and the query.</p>
<div class="sourceCode"><pre class="sourceCode literate haskell"><code class="sourceCode haskell"><span class="ot">main1 ::</span> <span class="dt">IO</span> ()
main1 <span class="fu">=</span> putStrLn <span class="fu">=<<</span> encode <span class="fu"><$></span> graphql schema1 query1</code></pre></div>
<p>This runs the query by fetching the one field defined, returning</p>
<p><code>{"data" : {"hello":"it's me"}}</code></p>
</section>
<section id="monadic-actions" class="level3">
<h3>Monadic actions</h3>
<p>For this example, we’re going to be using time.</p>
<div class="sourceCode"><pre class="sourceCode literate haskell"><code class="sourceCode haskell"><span class="ot">schema2 ::</span> <span class="dt">Schema</span> <span class="dt">IO</span>
schema2 <span class="fu">=</span> <span class="dt">Schema</span> [time]
<span class="ot">time ::</span> <span class="dt">Resolver</span> <span class="dt">IO</span>
time <span class="fu">=</span> Schema.scalarA <span class="st">"time"</span> <span class="fu">$</span> \<span class="kw">case</span>
[] <span class="ot">-></span> <span class="kw">do</span> t <span class="ot"><-</span> getCurrentTime
return <span class="fu">$</span> show t
_ <span class="ot">-></span> empty</code></pre></div>
<p>This defines a simple schema with one type and one field, which resolves to the current time.</p>
<p>Next we define our query.</p>
<div class="sourceCode"><pre class="sourceCode literate haskell"><code class="sourceCode haskell"><span class="ot">query2 ::</span> <span class="dt">Text</span>
query2 <span class="fu">=</span> <span class="st">"{ time }"</span>
<span class="ot">main2 ::</span> <span class="dt">IO</span> ()
main2 <span class="fu">=</span> putStrLn <span class="fu">=<<</span> encode <span class="fu"><$></span> graphql schema2 query2</code></pre></div>
<p>This runs the query, returning the current time</p>
<p><code>{"data": {"time":"2016-03-08 23:28:14.546899 UTC"}}</code></p>
</section>
<section id="errors" class="level3">
<h3>Errors</h3>
<p>Errors are handled according to the spec, with fields that cause erros being resolved to <code>null</code>, and an error being added to the error list.</p>
<p>An example of this is the following query:</p>
<div class="sourceCode"><pre class="sourceCode literate haskell"><code class="sourceCode haskell"><span class="ot">queryShouldFail ::</span> <span class="dt">Text</span>
queryShouldFail <span class="fu">=</span> <span class="st">"{ boyhowdy }"</span></code></pre></div>
<p>Since there is no <code>boyhowdy</code> field in our schema, it will not resolve, and the query will fail, as we can see in the following example.</p>
<div class="sourceCode"><pre class="sourceCode literate haskell"><code class="sourceCode haskell"><span class="ot">mainShouldFail ::</span> <span class="dt">IO</span> ()
mainShouldFail <span class="fu">=</span> <span class="kw">do</span>
r <span class="ot"><-</span> graphql schema1 query1
putStrLn <span class="fu">$</span> encode r
putStrLn <span class="st">"This will fail"</span>
r <span class="ot"><-</span> graphql schema1 queryShouldFail
putStrLn <span class="fu">$</span> encode r</code></pre></div>
<p>This outputs:</p>
<pre><code>{"data": {"hello": "it's me"}}
This will fail
{"data": {"boyhowdy": null}, "errors":[{"message": "the field boyhowdy did not resolve."}]}</code></pre>
</section>
<section id="combining-resolvers" class="level3">
<h3>Combining resolvers</h3>
<p>Now that we have two resolvers, we can define a schema which uses them both.</p>
<div class="sourceCode"><pre class="sourceCode literate haskell"><code class="sourceCode haskell"><span class="ot">schema3 ::</span> <span class="dt">Schema</span> <span class="dt">IO</span>
schema3 <span class="fu">=</span> <span class="dt">Schema</span> [hello, time]
<span class="ot">query3 ::</span> <span class="dt">Text</span>
query3 <span class="fu">=</span> <span class="st">"query timeAndHello { time hello }"</span>
<span class="ot">main3 ::</span> <span class="dt">IO</span> ()
main3 <span class="fu">=</span> putStrLn <span class="fu">=<<</span> encode <span class="fu"><$></span> graphql schema3 query3</code></pre></div>
<p>This queries for both time and hello, returning</p>
<p><code>{ "data": {"hello":"it's me","time":"2016-03-08 23:29:11.62108 UTC"}}</code></p>
<p>Notice that we can name our queries, as we did with <code>timeAndHello</code>. Since we have only been using single queries, we can use the shorthand <code>{ time hello}</code>, as we have been doing in the previous examples.</p>
<p>In GraphQL there can only be one operation per query.</p>
</section>
</section>
<section id="further-examples" class="level2">
<h2>Further examples</h2>
<p>More examples on queries and a more complex schema can be found in the test directory, in the <a href="../../tests/Test/StarWars">Test.StarWars</a> module. This includes a more complex schema, and more complex queries.</p>
</section>
</body>
</html>
|
