graphql/docs/tutorial/tutorial.rst

177 lines
4.0 KiB
ReStructuredText
Raw Normal View History

========================
GraphQL Haskell Tutorial
========================
.. contents::
:depth: 3
..
Getting started
===============
Welcome to graphql-haskell!
We have written a small tutorial to help you (and ourselves) understand
the graphql package.
Since this file is a literate haskell file, we start by importing some
dependencies.
.. code:: haskell
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE LambdaCase #-}
module Main where
import Prelude hiding (empty, putStrLn)
import Data.GraphQL
import Data.GraphQL.Schema
import qualified Data.GraphQL.Schema as Schema
import Control.Applicative
import Data.Text hiding (empty)
import Data.Aeson
import Data.ByteString.Lazy.Char8 (putStrLn)
import Data.Time
import Debug.Trace
First example
-------------
Now, as our first example, we are going to look at the example from
`graphql.js <https://github.com/graphql/graphql-js>`__.
First we build a GraphQL schema.
.. code:: haskell
schema1 :: Alternative f => Schema f
schema1 = Schema [hello]
hello :: Alternative f => Resolver f
hello = Schema.scalar "hello" ("it's me" :: Text)
This defines a simple schema with one type and one field, that resolves
to a fixed value.
Next we define our query.
.. code:: haskell
query1 :: Text
query1 = "{ hello }"
To run the query, we call the ``graphql`` with the schema and the query.
.. code:: haskell
main1 :: IO ()
main1 = putStrLn =<< encode <$> graphql schema1 query1
This runs the query by fetching the one field defined, returning
``{"data" : {"hello":"it's me"}}``
Monadic actions
---------------
For this example, we're going to be using time.
.. code:: haskell
schema2 :: Schema IO
schema2 = Schema [time]
time :: Resolver IO
time = Schema.scalarA "time" $ \case
[] -> do t <- getCurrentTime
return $ show t
_ -> empty
This defines a simple schema with one type and one field, which resolves
to the current time.
Next we define our query.
.. code:: haskell
query2 :: Text
query2 = "{ time }"
main2 :: IO ()
main2 = putStrLn =<< encode <$> graphql schema2 query2
This runs the query, returning the current time
``{"data": {"time":"2016-03-08 23:28:14.546899 UTC"}}``
Errors
------
Errors are handled according to the spec, with fields that cause erros
being resolved to ``null``, and an error being added to the error list.
An example of this is the following query:
.. code:: haskell
queryShouldFail :: Text
queryShouldFail = "{ boyhowdy }"
Since there is no ``boyhowdy`` field in our schema, it will not resolve,
and the query will fail, as we can see in the following example.
.. code:: haskell
mainShouldFail :: IO ()
mainShouldFail = do
r <- graphql schema1 query1
putStrLn $ encode r
putStrLn "This will fail"
r <- graphql schema1 queryShouldFail
putStrLn $ encode r
This outputs:
::
{"data": {"hello": "it's me"}}
This will fail
{"data": {"boyhowdy": null}, "errors":[{"message": "the field boyhowdy did not resolve."}]}
Combining resolvers
-------------------
Now that we have two resolvers, we can define a schema which uses them
both.
.. code:: haskell
schema3 :: Schema IO
schema3 = Schema [hello, time]
query3 :: Text
query3 = "query timeAndHello { time hello }"
main3 :: IO ()
main3 = putStrLn =<< encode <$> graphql schema3 query3
This queries for both time and hello, returning
``{ "data": {"hello":"it's me","time":"2016-03-08 23:29:11.62108 UTC"}}``
Notice that we can name our queries, as we did with ``timeAndHello``.
Since we have only been using single queries, we can use the shorthand
``{ time hello}``, as we have been doing in the previous examples.
In GraphQL there can only be one operation per query.
Further examples
================
More examples on queries and a more complex schema can be found in the
test directory, in the `Test.StarWars <../../tests/Test/StarWars>`__
module. This includes a more complex schema, and more complex queries.