From dea8eb3e4309c6b6a0aeb241e4c729e37efb0b26 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mateu=20Aguil=C3=B3=20Bosch?= <mateu.aguilo.bosch@gmail.com>
Date: Wed, 31 Oct 2018 00:45:34 +0100
Subject: [PATCH] docs: add better documentation

---
 .emdaer/README.emdaer.md  | 12 ++++++++++++
 .emdaer/docs/benefits.md  | 12 ++++++++++++
 .emdaer/docs/directive.md | 35 +++++++++++++++++++++++++++++++++++
 .emdaer/docs/header.md    | 13 ++++++++++---
 .emdaer/docs/install.md   | 12 +++++++++++-
 5 files changed, 80 insertions(+), 4 deletions(-)
 create mode 100644 .emdaer/docs/benefits.md
 create mode 100644 .emdaer/docs/directive.md

diff --git a/.emdaer/README.emdaer.md b/.emdaer/README.emdaer.md
index 94e5e4e..5768f9b 100644
--- a/.emdaer/README.emdaer.md
+++ b/.emdaer/README.emdaer.md
@@ -42,12 +42,24 @@
        style: 'flat-square'
 -->
 
+<!--emdaer-p
+  - '@emdaer/plugin-import'
+  - path: .emdaer/docs/benefits.md
+    runEmdaer: false
+-->
+
 <!--emdaer-p
   - '@emdaer/plugin-import'
   - path: .emdaer/docs/install.md
     runEmdaer: false
 -->
 
+<!--emdaer-p
+  - '@emdaer/plugin-import'
+  - path: .emdaer/docs/directive.md
+    runEmdaer: false
+-->
+
 ## Contributors
 <!--emdaer-p
   - '@emdaer/plugin-contributors-details-github'
diff --git a/.emdaer/docs/benefits.md b/.emdaer/docs/benefits.md
new file mode 100644
index 0000000..e5c0d7a
--- /dev/null
+++ b/.emdaer/docs/benefits.md
@@ -0,0 +1,12 @@
+## Benefits of GraphQL in node.js
+The most obvious benefit of having GraphQL in node.js is that you can aggregate different APIs under a single GraphQL
+back-end in a non-blocking I/O runtime. This will **improve performance dramatically**.
+
+Another obvious benefit is that by using the [Apollo Server](https://www.apollographql.com/) you get **many** [features
+for free](https://www.apollographql.com/docs/apollo-server/v2/) (like mocking, persited queries, cache hint directives,
+and many [additional packages](https://github.com/apollographql/apollo-server/tree/master/packages)). And even more if
+your consumers use the [Apollo Client](https://www.apollographql.com/docs/react/).
+
+Another outstanding benefit is that by using [GraphQL.js](https://github.com/graphql/graphql-js) you are depending on
+the reference implementation of GraphQL. That means that it is supported by the official GraphQL team. It also means
+that it has extensive support and a wide [community](https://graphql.org/community/).
diff --git a/.emdaer/docs/directive.md b/.emdaer/docs/directive.md
new file mode 100644
index 0000000..13e6381
--- /dev/null
+++ b/.emdaer/docs/directive.md
@@ -0,0 +1,35 @@
+## The `@fromJsonApi(…)` directive
+The `@fromJsonApi(…)` is the biggest motivator of this repository. Since JSON API allows you to get _the information you
+need and only the information you need, in a single request_, it is the perfect data fetcher for your GraphQL.js
+project.
+
+This directive will intelligently turn the response from JSON API into the hierarchical format that GraphQL expects.
+This includes all the nested relationships at all levels. This leaves everything ready for the user to start selecting
+fields for the response.
+
+### Examples
+
+```graphql
+ type Query {
+  lastRecipe: Recipe
+    @fromJsonApi(
+      query: "/recipes?page[limit]=1&sort=createdAt&include=author"
+    )
+  recipesByAuthor(authorName: String!): [Recipe]
+    @fromJsonApi(
+      query: "/recipes?filter[author.name]={authorName}&include=author"
+    )
+  articlesByAuthor(authorName: String!): [Article]
+    @fromJsonApi(
+      query: "/articles?filter[owner.name]={authorName}&include=owner"
+    )
+}
+```
+
+Note how you can specify a templated URL with variables. The replacement value for these variables will be specified in
+the query. For instance see how the `{authorName}` value is provided in the GraphQL query below:
+
+```
+curl -X GET \
+  'http://localhost:3000/graphql?query={recipesByAuthor(authorName:"Umami"){title,id,random,author{name}}}'
+```
diff --git a/.emdaer/docs/header.md b/.emdaer/docs/header.md
index 4839818..87f2095 100644
--- a/.emdaer/docs/header.md
+++ b/.emdaer/docs/header.md
@@ -1,11 +1,18 @@
-ContentaJS GraphQL is a repository that contains a set of helpers to build your
-GraphQL project on top of Contenta.js
+ContentaJS GraphQL is a repository that contains a set of helpers to build your GraphQL project on top of Contenta JS.
 
 <!--emdaer-p
   - '@emdaer/plugin-image'
   - src: ./.emdaer/docs/assets/graphql.png
     alt: GraphQL
     align: center
+    width: 60%
 -->
 
-**IMPORTANT:** I need to finish this…
+This project provides a simple Apollo server instance that you can use in your Contenta JS application. It ships wit a
+very convenient [GraphQL directive](https://www.apollographql.com/docs/graphql-tools/schema-directives.html) that will
+fetch data from your Contenta CMS back-end using JSON API. The result of that data fetch will be parsed and prepared so
+it can be resolved by GraphQL without additional work.
+
+You can see this is action in the [`graphql-example-code`](https://github.com/contentacms/contentajs/tree/graphql-example-code)
+branch. If you prefer, you can see [the diff](https://github.com/contentacms/contentajs/compare/9b95bba53e47220129fcf2e84eed9ceedff119d9...graphql-example-code?expand=1).
+That will show the necessary code to add GraphQL to your Contenta project.
diff --git a/.emdaer/docs/install.md b/.emdaer/docs/install.md
index 7c35053..9350940 100644
--- a/.emdaer/docs/install.md
+++ b/.emdaer/docs/install.md
@@ -1,2 +1,12 @@
 ## Installation
-TODO
+You can see an example of this in this [demo code](https://github.com/contentacms/contentajs/compare/9b95bba53e47220129fcf2e84eed9ceedff119d9...graphql-example-code?expand=1).
+1. Inside of your Contenta JS project add the necessary dependencies
+```
+npm install --save @contentacms/contentajs-graphql graphql graphql-tools
+```
+2. [Create a server instance with the Contena CMS URL and add it to express](https://github.com/contentacms/contentajs/compare/9b95bba53e47220129fcf2e84eed9ceedff119d9...graphql-example-code?expand=1#diff-f4fed62a72fc59b66a2183017cc4b9cb).
+3. Write your GraphQL types.
+  - If they follow the structure of your JSON API resources they'll get automatically resolved. See [this example of an Article type](https://github.com/contentacms/contentajs/compare/9b95bba53e47220129fcf2e84eed9ceedff119d9...graphql-example-code?expand=1#diff-da57a422b90e697b0a5bbe0a11699b7a).
+  - If there are any additional fields, you can resolve them _the GraphQL way_. This example [creates an extra field called random](https://github.com/contentacms/contentajs/compare/9b95bba53e47220129fcf2e84eed9ceedff119d9...graphql-example-code?expand=1#diff-2be3149c012f9a61fb6bbd290edde707R9).
+    In order to resolve the value of `random` you will need a resolver like [this one](https://github.com/contentacms/contentajs/compare/9b95bba53e47220129fcf2e84eed9ceedff119d9...graphql-example-code?expand=1#diff-895614263fb87c38476aeb8dad289b12).
+4. THAT'S IT.