From 2679ba05f3b7124b32cbb391220a23d0c8b7656d Mon Sep 17 00:00:00 2001
From: Diana Lau <dhmlau@ca.ibm.com>
Date: Mon, 22 Oct 2018 16:15:28 -0400
Subject: [PATCH] docs: add tutorial to expose GraphQL APIs

---
 docs/site/exposing-graphql-apis.md | 117 +++++++++++++++++++++++++++++
 docs/site/sidebars/lb4_sidebar.yml |  15 +++-
 2 files changed, 129 insertions(+), 3 deletions(-)
 create mode 100644 docs/site/exposing-graphql-apis.md

diff --git a/docs/site/exposing-graphql-apis.md b/docs/site/exposing-graphql-apis.md
new file mode 100644
index 000000000000..c88dad98945f
--- /dev/null
+++ b/docs/site/exposing-graphql-apis.md
@@ -0,0 +1,117 @@
+---
+lang: en
+title: 'Exposing GraphQL APIs'
+keywords: LoopBack 4.0, LoopBack 4, GraphQL
+sidebar: lb4_sidebar
+permalink: /doc/en/lb4/exposing-graphql-apis.html
+---
+
+## Overview
+
+The [OASGraph module](https://www.npmjs.com/package/oasgraph) creates a GraphQL
+wrapper for existing REST APIs which are described by the OpenAPI specification.
+This tutorial shows how to expose GraphQL APIs in an existing LoopBack
+application.
+
+### Prerequisite
+
+Make sure you have a running LoopBack 4 application. In this tutorial, we'll use
+the `todo` example. You can create this application by running the command
+below:
+
+```sh
+lb4 example todo
+```
+
+### Install OASGraph and Required Dependencies
+
+From your LoopBack application, run the following command to install OASGraph
+and the required dependencies:
+
+```sh
+npm i --save oasgraph express express-graphql
+```
+
+### Start the GraphQL Server
+
+Make sure your LoopBack application is running by going to
+`http://localhost:3000/openapi.json`. If not, you can start it by running the
+`npm start` command.
+
+Now we will use the oasgraph CLI to set up a GraphQL HTTP Server backed by
+express on port 3001. Specifying the OpenAPI spec generated by the
+todo-application as the parameter, start up the server by running the following
+command:
+
+```sh
+npx oasgraph http://localhost:3000/openapi.json
+```
+
+_Haven't heard about `npx` yet? It's a cool helper provided by `npm` and
+available out of the box since Node.js 8.x. Learn more in their announcement
+blog post:
+[Introducing npx: an npm package runner](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b))_
+
+That’s it! You’re now ready to try out some tests and requests in the browser at
+http://localhost:3001/graphql.
+
+{% include note.html content="
+We are looking into ways how to expose the GraphQL endpoint alongside the main REST API,
+on the same HTTP host and port. See
+[issue #1905](https://github.com/strongloop/loopback-next/issues/1905).
+" %}
+
+### Try Out the GraphQL APIs
+
+Here are some examples of the `query` and `mutation` calls:
+
+1. To get all the to-do instances, run this query command:
+
+```
+ query{
+   todos {
+     id
+     title
+     desc
+   }
+ }
+```
+
+The expected output looks like this:
+
+```json
+{ "data": { "todos": [
+      { "id": 1, "title": "Take over the galaxy", "desc": "MWAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHAHA" },
+      { "id": 2, "title": "destroy alderaan", "desc": "Make sure there are no survivors left!" },
+      {"id": 3, "title": "terrorize senate", "desc": "Tell them they're getting a budget
+  cut." },
+      { "id": 4, "title": "crush rebel scum", "desc": "Every.Last.One." }
+] } }
+```
+
+2. Create a to-do instance and retrieve its ID and title in the response object
+   using the following mutation command:
+
+```
+ mutation {
+   postTodos(todoInput: {
+     title: "Take over the universe"
+   }) {
+     id
+     title
+   }
+ }
+```
+
+The expected output looks like this:
+
+```json
+{
+  "data": {
+    "postTodos": {
+      "id": 5,
+      "title": "Take over the universe"
+    }
+  }
+}
+```
diff --git a/docs/site/sidebars/lb4_sidebar.yml b/docs/site/sidebars/lb4_sidebar.yml
index 9377de47acf9..3d806f1d5c47 100644
--- a/docs/site/sidebars/lb4_sidebar.yml
+++ b/docs/site/sidebars/lb4_sidebar.yml
@@ -98,9 +98,6 @@ children:
     - title: 'Run and Test it'
       url: soap-calculator-tutorial-run-and-test.html
       output: 'web, pdf'
-  - title: 'Deploying to IBM Cloud'
-    url: Deploying-to-IBM-Cloud.html
-    output: 'web, pdf'
 
 - title: 'Key concepts'
   url: Concepts.html
@@ -194,6 +191,18 @@ children:
     url: Error-handling.html
     output: 'web, pdf'
 
+- title: 'How tos'
+  url: Concepts.html
+  output: 'web, pdf'
+  children:
+    - title: 'Exposing GraphQL APIs'
+      url: exposing-graphql-apis.html
+      output: 'web, pdf'
+
+    - title: 'Deploying to IBM Cloud'
+      url: Deploying-to-IBM-Cloud.html
+      output: 'web, pdf'
+
 - title: 'Booting an Application'
   url: Booting-an-Application.html
   output: 'web, pdf'