diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 124 |
1 files changed, 5 insertions, 119 deletions
@@ -1,9 +1,7 @@ # GraphQL implementation in Haskell -[](https://hackage.haskell.org/package/graphql) -[](https://github.com/caraus-ecms/graphql/actions?query=workflow%3A%22Haskell+CI%22) -[](https://raw.githubusercontent.com/caraus-ecms/graphql/master/LICENSE) [](https://www.simplehaskell.org) +[](https://build.caraus.tech/go/pipelines) This implementation is relatively low-level by design, it doesn't provide any mappings between the GraphQL types and Haskell's type system and avoids @@ -24,125 +22,13 @@ For now this library provides: But the idea is to be a Haskell port of [`graphql-js`](https://github.com/graphql/graphql-js). -For a more precise list of currently missing features see issues marked as -"[not implemented](https://github.com/caraus-ecms/graphql/labels/not%20implemented)". +For a more precise list of currently missing features see +[issues](https://www.caraus.tech/projects/pub-graphql/issues). ## Documentation API documentation is available through [Hackage](https://hackage.haskell.org/package/graphql). -You'll also find a small tutorial with some examples under -[docs/tutorial](https://github.com/caraus-ecms/graphql/tree/master/docs/tutorial). - -### Getting started - -We start with a simple GraphQL API that provides us with some famous and less -famous cites. - -```graphql -""" -Root Query type. -""" -type Query { - """ - Provides a cite. - """ - cite: String! -} -``` - -This is called a GraphQL schema, it defines all queries supported by the API. -`Query` is the root query type. Every GraphQL API should define a query type. - -`Query` has a single field `cite` that returns a `String`. The `!` after the -type denotes that the returned value cannot be `Null`. GraphQL fields are -nullable by default. - -To be able to work with this schema, we are going to implement it in Haskell. - -```haskell -{-# LANGUAGE OverloadedStrings #-} - -import Control.Exception (SomeException) -import qualified Data.Aeson as Aeson -import qualified Data.ByteString.Lazy.Char8 as ByteString.Lazy.Char8 -import qualified Data.HashMap.Strict as HashMap -import Language.GraphQL -import Language.GraphQL.Type -import qualified Language.GraphQL.Type.Out as Out - --- GraphQL supports 3 kinds of operations: queries, mutations and subscriptions. --- Our first schema supports only queries. -schema :: Schema IO -schema = Schema - { query = queryType, mutation = Nothing, subscription = Nothing } - --- GraphQL distinguishes between input and output types. Input types are field --- argument types and they are defined in Language.GraphQL.Type.In. Output types --- are result types, they are defined in Language.GraphQL.Type.Out. Root types --- are always object types. --- --- Here we define a type "Query". The second argument is an optional --- description, the third one is the list of interfaces implemented by the --- object type. The last argument is a field map. Keys are field names, values --- are field definitions and resolvers. Resolvers are the functions, where the --- actual logic lives, they return values for the respective fields. -queryType :: Out.ObjectType IO -queryType = Out.ObjectType "Query" (Just "Root Query type.") [] - $ HashMap.singleton "cite" citeResolver - where - -- 'ValueResolver' is a 'Resolver' data constructor, it combines a field - -- definition with its resolver function. This function resolves a value for - -- a field (as opposed to the 'EventStreamResolver' used by subscriptions). - -- Our resolver just returns a constant value. - citeResolver = ValueResolver citeField - $ pure "Piscis primum a capite foetat" - -- The first argument is an optional field description. The second one is - -- the field type and the third one is for arguments (we have none in this - -- example). - -- - -- GraphQL has named and wrapping types. String is a scalar, named type. - -- Named types are nullable by default. To make our "cite" field - -- non-nullable, we wrap it in the wrapping type, Non-Null. - citeField = Out.Field - (Just "Provides a cite.") (Out.NonNullScalarType string) HashMap.empty - --- Now we can execute a query. Since our schema defines only one field, --- everything we can do is to ask to resolve it and give back the result. --- Since subscriptions don't return plain values, the 'graphql' function returns --- an 'Either'. 'Left' is for subscriptions, 'Right' is for queries and --- mutations. -main :: IO () -main = do - Right result <- graphql schema "{ cite }" - ByteString.Lazy.Char8.putStrLn $ Aeson.encode result -``` - -Executing this query produces the following JSON: - -```json -{ - "data": { - "cite": "Piscis primum a capite foetat" - } -} -``` - -## Further information - -- [Contributing guidelines](CONTRIBUTING.md). -- [Changelog](CHANGELOG.md) – this one contains the most recent changes; - individual changelogs for specific versions can be found on - [Hackage](https://hackage.haskell.org/package/graphql). - -## Contact - -Suggestions, contributions and bug reports are welcome. - -Should you have questions on usage, please open an issue and ask – this helps -to write useful documentation. - -Feel free to contact on Slack in [#haskell on -GraphQL](https://graphql.slack.com/messages/haskell/). You can obtain an -invitation [here](https://graphql-slack.herokuapp.com/). +Further documentation will be made available in the +[Wiki](https://www.caraus.tech/projects/pub-graphql/wiki). |