Merge pull request #1456 from coralproject/docs

GraphQL Docs Fixes
2026-07-06 05:17:19 +08:00 · 2018-03-21 15:34:27 -04:00
parent 1f0630d875 f4575e2075
commit 5f526eb49c
10 changed files with 246 additions and 50 deletions
@@ -146,10 +146,12 @@ sidebar:
          url: /customizing-plugins-coral-ui/
    - title: API
      children:
-        - title: Server Plugins
-          url: /reference/server/
-        - title: GraphQL
-          url: /reference/graphql/
+        - title: GraphQL Overview
+          url: /api/overview/
+        - title: GraphQL Reference
+          url: /api/graphql/
+        - title: Server Plugin API
+          url: /api/server/
    - title: Migrating
      children:
        - title: Migrating to v4.0.0
@@ -1 +1,3 @@
-/ /talk/
+/ /talk/
+/talk/reference/server/ /talk/api/server/
+/talk/reference/graphql/ /talk/api/graphql/
@@ -1,9 +1,15 @@
 ---
-title: GraphQL API
-permalink: /reference/graphql/
+title: GraphQL API Reference
+permalink: /api/graphql/
 ---

 We provide all services that Talk can provide via the GraphQL API documented
 below. For a primer about GraphQL, visit http://graphql.org/.

+If you're already familiar with GraphQL, visit
+[GraphQL API Overview](/talk/api/overview/) to see how to
+interact with Talk's GraphQL endpoint.
+
+# GraphQL Schema
+
 {% graphqldocs ../../client/coral-framework/graphql/introspection.json %}
@@ -0,0 +1,196 @@
+---
+title: GraphQL API Overview
+permalink: /api/overview/
+---
+
+We provide all services that Talk can provide via the GraphQL API documented
+on our [GraphQL API Reference](/talk/api/graphql/). If you've never heard
+about GraphQL before, visit http://graphql.org/ to learn the basics first.
+
+## Development
+
+During development mode (when Talk has `NODE_ENV=development`) Talk will enable
+the GraphiQL IDE at the following route:
+
+    ${ROOT_URL}api/v1/graph/iql
+
+This is pretty powerful, as it lets you explore the API documentation on the
+sidebar as well as send off requests.
+
+## Making your first request
+
+To learn a bit about how to interact with Talk, we'll query for comments on a
+page of Talk. I have Talk running locally, (If you don't and want to, checkout
+our [Talk Quickstart](/talk/)).
+
+The GraphQL endpoint we have can be used with any HTTP client available, but our
+examples below will use the common `curl` tool:
+
+```sh
+curl --request POST \
+  --url http://localhost:3000/api/v1/graph/ql \
+  --header 'Content-Type: application/json' \
+  --data '{"query":"query GetComments($url: String!) { asset(url: $url) { title url comments { nodes { body user { username } } } }}","variables":{"url":"http://localhost:3000/"},"operationName":"GetComments"}'
+```
+
+When you unpack that, it's really quite simple. We're executing a `POST` request
+to the `/api/v1/graph/ql` route of the local Talk server with the GraphQL
+request we want to make. It's composed of the `query`, `variables`, and
+`operationName`.
+
+```graphql
+query GetComments($url: String!) {
+  asset(url: $url) {
+    title
+    url
+    comments {
+      nodes {
+        body
+        user {
+          username
+        }
+      }
+    }
+  }
+}
+```
+
+The query itself is quite straightforward, we are grabbing the asset with the
+specified `$url`, and grabbing it's title and the comments also (You can also
+look at our [GraphQL API Reference](/talk/api/graphql/) for our entire schema).
+
+We can then also specify our variables to the query being executed (in this
+case, the url for the page where we have comments on our local install of Talk):
+
+```json
+{
+    "url": "http://localhost:3000/"
+}
+```
+
+It's also sometimes common to have multiple queries within a query, which is
+where the `operationName` comes into play, where we simply specify the named
+query that we want to execute (in this case, `GetComments`).
+
+To get a deeper understanding of GraphQL queries, read up on
+[GraphQL Queries and Mutations](http://graphql.org/learn/queries/).
+
+## Understanding the response
+
+Once you completed the above GraphQL query with `curl`, you'll get a response
+sort of like this:
+
+```json
+{
+  "data": {
+    "asset": {
+      "title": "Coral Talk",
+      "url": "http://localhost:3000/",
+      "comments": {
+        "nodes": [
+          {
+            "body": "Second comment!",
+            "user": {
+              "username": "wyattjoh"
+            }
+          },
+          {
+            "body": "First comment!",
+            "user": {
+              "username": "wyattjoh"
+            }
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+All of the parameters you requested should be available under the `data`
+property. Any errors that you get would appear in a `errors` array at the top
+level, like this:
+
+```json
+{
+  "data": {
+    "asset": null
+  },
+  "errors": [
+    {
+      "message": "asset_url is invalid",
+      "locations": [
+        {
+          "line": 2,
+          "column": 3
+        }
+      ],
+      "path": [
+        "asset"
+      ]
+    }
+  ]
+}
+```
+
+You should know that any property that is marked with a `!` is considered
+required, and non-nullable, which means you can always guarantee on it being
+there in your request if there were no errors.
+
+## Authorizing a request
+
+Some queries you may notice seem to return `null` or an error of
+`NOT_AUTHORIZED`. It's likely the case that you are making a request to a
+route that requires authorization. You can perform authorization a few ways in
+Talk:
+
+1. As a [Bearer Token](#Bearer-Token)
+2. As a [Query Parameter](#Query-Parameter)
+3. As a [Cookie](#Cookie)
+
+Essentially, you need to get access to a JWT token that you can use to authorize
+your requests. Generating one is simple, you can use the CLI tools in Talk to do
+that.
+
+```sh
+# first, find your user account
+./bin/cli users list
+
+# then, create a token for that account
+./bin/cli token create ${USER_ID} example-token
+```
+
+Where `USER_ID` is the ID of your user account you found using the `users list`
+command.
+
+Once you have your access token, you can substitute it as `${TOKEN}` in your
+`curl` request as follows:
+
+### Bearer Token
+
+```sh
+curl --request POST \
+  --url http://localhost:3000/api/v1/graph/ql \
+  --header 'Content-Type: application/json' \
+  --header "Authorization: Bearer ${TOKEN}"
+  --data '{"query":"query GetComments($url: String!) { asset(url: $url) { title url comments { nodes { body user { username } } } }}","variables":{"url":"http://localhost:3000/"},"operationName":"GetComments"}'
+```
+
+### Query Parameter
+
+```sh
+curl --request POST \
+  --url http://localhost:3000/api/v1/graph/ql?access_token=${TOKEN} \
+  --header 'Content-Type: application/json' \
+  --data '{"query":"query GetComments($url: String!) { asset(url: $url) { title url comments { nodes { body user { username } } } }}","variables":{"url":"http://localhost:3000/"},"operationName":"GetComments"}'
+```
+
+### Cookie
+
+```sh
+curl --request POST \
+  --url http://localhost:3000/api/v1/graph/ql \
+  --header 'Content-Type: application/json' \
+  --cookie "authorization=${TOKEN}"
+  --data '{"query":"query GetComments($url: String!) { asset(url: $url) { title url comments { nodes { body user { username } } } }}","variables":{"url":"http://localhost:3000/"},"operationName":"GetComments"}'
+```
@@ -1,6 +1,6 @@
 ---
 title: Server Plugin API
-permalink: /reference/server/
+permalink: /api/server/
 toc: true
 class: configuration
 ---
@@ -3,7 +3,7 @@
 const path = require('path');
 const fs = require('fs');
 const { stripIndent } = require('common-tags');
-const docs = fs.readFileSync(
+const docsScript = fs.readFileSync(
  require.resolve('graphql-docs/dist/graphql-docs.min.js'),
  { encoding: 'utf8' }
 );
@@ -16,7 +16,7 @@ hexo.extend.tag.register('graphqldocs', args => {
    <div id="graphql-docs"></div>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/react/15.0.2/react.min.js" integrity="sha256-oj3q2t3QPvtdjo4M5gZfrAXyHEfTfvYdfRL2jA2ZfOY=" crossorigin="anonymous"></script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/react/15.0.2/react-dom.min.js" integrity="sha256-sqgMIZkGTh7B/tF2nSyXc+tGBYCsfWiTl2II167jrOQ=" crossorigin="anonymous"></script>
-    <script>${docs}</script>
+    <script>${docsScript}</script>
    <script>
        function fetcher() {
            return new Promise(function(resolve) {
@@ -1,5 +1,6 @@
 const {
  makeExecutableSchema,
+  addResolveFunctionsToSchema,
  addSchemaLevelResolveFunction,
 } = require('graphql-tools');
 const debug = require('debug')('talk:graph:schema');
@@ -10,7 +11,10 @@ const plugins = require('../services/plugins');
 const resolvers = require('./resolvers');
 const typeDefs = require('./typeDefs');

-const schema = makeExecutableSchema({ typeDefs, resolvers });
+const schema = makeExecutableSchema({ typeDefs });
+
+// Add the resolvers to the schema
+addResolveFunctionsToSchema(schema, resolvers);

 // Plugin to the schema level resolvers to provide an before/after hook.
 decorateWithHooks(schema, plugins.get('server', 'hooks'));
@@ -1,10 +1,6 @@
-// TODO: Adjust `RootQuery.asset(id: ID, url: String)` to instead be
-// `RootQuery.asset(id: ID, url: String!)` because we'll always need the url, if
-// this change is done now everything will likely break on the front end.
-
 const fs = require('fs');
 const path = require('path');
-const { mergeStrings } = require('gql-merge');
+const { mergeStrings } = require('@coralproject/gql-merge');
 const debug = require('debug')('talk:graph:typeDefs');
 const plugins = require('../services/plugins');

@@ -54,6 +54,7 @@
  },
  "homepage": "https://github.com/coralproject/talk#readme",
  "dependencies": {
+    "@coralproject/gql-merge": "^0.1.0",
    "@coralproject/graphql-anywhere-optimized": "^0.1.0",
    "accepts": "^1.3.4",
    "apollo-client": "^1.9.1",
@@ -106,7 +107,6 @@
    "file-loader": "^0.11.2",
    "form-data": "^2.3.1",
    "fs-extra": "^4.0.1",
-    "gql-merge": "^0.0.4",
    "graphql": "^0.10.1",
    "graphql-ast-tools": "0.2.3",
    "graphql-docs": "0.2.0",
@@ -80,6 +80,19 @@
    eslint-plugin-react "^7.5.1"
    prettier "^1.10.2"

+"@coralproject/gql-format@^0.1.0":
+  version "0.1.0"
+  resolved "https://registry.yarnpkg.com/@coralproject/gql-format/-/gql-format-0.1.0.tgz#76a0f9a672076482f665781d0c09e39e14f70491"
+  dependencies:
+    graphql "0.9.2"
+
+"@coralproject/gql-merge@^0.1.0":
+  version "0.1.2"
+  resolved "https://registry.yarnpkg.com/@coralproject/gql-merge/-/gql-merge-0.1.2.tgz#3e5c79e1da71eb713a4eb3df16f64eaa3de2bad5"
+  dependencies:
+    "@coralproject/gql-format" "^0.1.0"
+    graphql "0.9.2"
+
 "@coralproject/graphql-anywhere-optimized@^0.1.0":
  version "0.1.6"
  resolved "https://registry.yarnpkg.com/@coralproject/graphql-anywhere-optimized/-/graphql-anywhere-optimized-0.1.6.tgz#073b33764c04788b0290788da9ebf0ed21af6437"
@@ -1354,7 +1367,7 @@ bluebird@3.5.0:
  version "3.5.0"
  resolved "https://registry.yarnpkg.com/bluebird/-/bluebird-3.5.0.tgz#791420d7f551eea2897453a8a77653f96606d67c"

-bluebird@^3.0.6, bluebird@^3.1.1, bluebird@^3.2.2, bluebird@^3.3.4, bluebird@^3.4.0, bluebird@^3.4.6, bluebird@^3.5.0, bluebird@^3.5.1:
+bluebird@^3.0.6, bluebird@^3.1.1, bluebird@^3.2.2, bluebird@^3.3.4, bluebird@^3.4.0, bluebird@^3.5.0, bluebird@^3.5.1:
  version "3.5.1"
  resolved "https://registry.yarnpkg.com/bluebird/-/bluebird-3.5.1.tgz#d9551f9de98f1fcda1e683d17ee91a0602ee2eb9"

@@ -4284,29 +4297,6 @@ got@^6.7.1:
    unzip-response "^2.0.1"
    url-parse-lax "^1.0.0"

-gql-format@^0.0.4:
-  version "0.0.4"
-  resolved "https://registry.yarnpkg.com/gql-format/-/gql-format-0.0.4.tgz#8237de7647de37f00aba2d0073abf6087e2da119"
-  dependencies:
-    commander "^2.9.0"
-    graphql "^0.7.2"
-
-gql-merge@^0.0.4:
-  version "0.0.4"
-  resolved "https://registry.yarnpkg.com/gql-merge/-/gql-merge-0.0.4.tgz#1cb1d4cc8bb8768172cf08a45c5a4fbd0ecedc9f"
-  dependencies:
-    commander "^2.9.0"
-    gql-format "^0.0.4"
-    gql-utils "^0.0.2"
-    graphql "^0.7.2"
-
-gql-utils@^0.0.2:
-  version "0.0.2"
-  resolved "https://registry.yarnpkg.com/gql-utils/-/gql-utils-0.0.2.tgz#962b3c1b34bf965a45d2564a93d3072921f61e86"
-  dependencies:
-    bluebird "^3.4.6"
-    glob "^7.1.1"
-
 graceful-fs@^4.1.11, graceful-fs@^4.1.2, graceful-fs@^4.1.3, graceful-fs@^4.1.4, graceful-fs@^4.1.6, graceful-fs@^4.1.9:
  version "4.1.11"
  resolved "https://registry.yarnpkg.com/graceful-fs/-/graceful-fs-4.1.11.tgz#0e8bdfe4d1ddb8854d64e04ea7c00e2a026e5658"
@@ -4382,18 +4372,18 @@ graphql-tools@^0.10.1:
  optionalDependencies:
    "@types/graphql" "^0.8.5"

+graphql@0.9.2:
+  version "0.9.2"
+  resolved "https://registry.yarnpkg.com/graphql/-/graphql-0.9.2.tgz#2cb5c635de13f790a77c5879649cb401b1589386"
+  dependencies:
+    iterall "1.0.3"
+
 graphql@^0.10.0, graphql@^0.10.1, graphql@^0.10.3:
  version "0.10.5"
  resolved "https://registry.yarnpkg.com/graphql/-/graphql-0.10.5.tgz#c9be17ca2bdfdbd134077ffd9bbaa48b8becd298"
  dependencies:
    iterall "^1.1.0"

-graphql@^0.7.2:
-  version "0.7.2"
-  resolved "https://registry.yarnpkg.com/graphql/-/graphql-0.7.2.tgz#cc894a32823399b8a0cb012b9e9ecad35cd00f72"
-  dependencies:
-    iterall "1.0.2"
-
 growl@1.9.2:
  version "1.9.2"
  resolved "https://registry.yarnpkg.com/growl/-/growl-1.9.2.tgz#0ea7743715db8d8de2c5ede1775e1b45ac85c02f"
@@ -5567,9 +5557,9 @@ istanbul-reports@^1.1.2:
  dependencies:
    handlebars "^4.0.3"

-iterall@1.0.2:
-  version "1.0.2"
-  resolved "https://registry.yarnpkg.com/iterall/-/iterall-1.0.2.tgz#41a2e96ce9eda5e61c767ee5dc312373bb046e91"
+iterall@1.0.3:
+  version "1.0.3"
+  resolved "https://registry.yarnpkg.com/iterall/-/iterall-1.0.3.tgz#e0b31958f835013c323ff0b10943829ac69aa4b7"

 iterall@^1.1.0, iterall@^1.1.1:
  version "1.1.3"