fixed graphql docs, added graphql tutorial

2026-07-10 23:07:13 +08:00 · 2018-03-20 15:39:38 -06:00
parent 55e829ca66
commit ff24f521be
10 changed files with 246 additions and 50 deletions
@@ -0,0 +1,15 @@
+---
+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"}'
+```
@@ -0,0 +1,527 @@
+---
+title: Server Plugin API
+permalink: /api/server/
+toc: true
+class: configuration
+---
+
+The server functionality of our plugin lives inside the `index.js` plugin folder
+that exports the configuration of our plugin.
+
+            my-plugin/
+            ├── client/
+            │   └── ... <-- client side plugin files
+            └── index.js <-- base + server plugin index
+
+## Hooks
+
+Each plugin should export a single object with all hooks available on it.
+
+_**Note: You will have access to the whole core and other plugin's typeDefs,
+context, loaders, mutators, resolvers, hooks. This is intentional, as it
+encourages composing plugins to merge functionality, like a Slack plugin which
+provides a Slack notify context function as well as having the loader for
+comments.**_
+
+The following are the hooks available:
+
+### typeDefs
+
+```graphql
+enum COLOUR {
+  RED
+  BLUE
+}
+
+type Person {
+  name: String!
+  colour: COLOUR!
+}
+
+type RootMutation {
+  createPerson(name: String!): Person
+}
+
+type RootQuery {
+  people: [Person!]
+}
+
+type Subscription {
+  leader: Person
+}
+```
+
+Thanks to [gql-merge](https://www.npmjs.com/package/gql-merge) the contents of
+`typeDefs` should be a string that will be _merged_ with the existing type
+definitions. `enum`'s will be appended to, types will be appended, and new types
+will be added.
+
+### context
+
+```js
+{
+  Slack: (context) => ({
+    notify: (message) => {
+      // return a promise after we're done sending notifications.
+    }
+  })
+}
+```
+
+Any property provided here will be added to the context parameter available
+inside all resolvers, loaders, mutators, and of course, other context based
+plugins.
+
+The top level item must accept a context for the request which it should use to
+configure the context plugin before it would be mounted at `context.plugins`.
+This plugin above would mount at: `context.plugins.Slack`, or, if you're using
+[object destructuring](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment), `{plugins: {Slack}}`.
+
+### Sort
+
+A special context hook, `Sort` will allow plugin authors to provide new
+methods to sort data. An example is as follows:
+
+```js
+{
+  Sort: () => ({
+    Comments: { // <-- (1)
+      likes: { // <-- (2)
+        startCursor(ctx, nodes, {cursor}) { // <-- (3)
+          return cursor != null ? cursor : 0;
+        },
+        endCursor(ctx, nodes, {cursor}) { // <-- (4)
+          return nodes.length ? (cursor != null ? cursor : 0) + nodes.length : null;
+        },
+        sort(ctx, query, {cursor, sort}) { // <-- (5)
+          if (cursor) {
+            query = query.skip(cursor);
+          }
+
+          return query.sort({
+            'action_counts.like': sort === 'DESC' ? -1 : 1,
+            created_at: sort === 'DESC' ? -1 : 1,
+          });
+        },
+      },
+    },
+  }),
+}
+```
+
+This has a bunch of special features:
+
+1. `Comments` is the name of the type being sorted, this is pluralized and
+    capitalized.
+2. `likes` is the `sortBy` field in lowercase.
+3. `startCursor` will retrieve the start cursor based on the current set of
+    nodes and the current cursor.
+4. `endCursor` will retrieve the end cursor based on the current set of nodes
+    and the current cursor.
+5. `sort` will mutate the `query` to apply the sort operations.
+
+All the `startCursor`, `endCursor`, and `sort` functions must be provided in
+order for the sorting to apply properly.
+
+### loaders
+
+```js
+(context) => ({
+  People: {
+    load: () => db.people.find({user: context.user})
+  }
+})
+```
+
+Loaders should be provided as a function which returns a map which is used in
+the resolvers function. These must return a promise or a value.
+
+### mutators
+
+```js
+(context) => ({
+  People: {
+    create: (name) => {
+      return db.people.insert({user: context.user, name});
+    }
+  }
+})
+```
+
+Mutators should be provided as a function which returns a map which is used in
+the resolvers function. These must return a promise or a value.
+
+### resolvers
+
+```js
+{
+  Person: {
+    name(obj, args, context) {
+      return obj.name;
+    },
+    colour(obj, args, context) {
+      // Bill likes the colour red, everyone else likes blue.
+      return obj.name === 'bill' ? 'RED' : 'BLUE';
+    }
+  },
+  RootQuery: {
+    people(obj, args, {loaders: {People}}) {
+      return People.load();
+    }
+  },
+  RootMutation: {
+    createPerson(obj, {name}, {mutators: {People}}) {
+      return People.create(name);
+    }
+  }
+}
+```
+
+Should return a resolver map as described in the
+[Apollo Docs](http://dev.apollodata.com/tools/graphql-tools/resolvers#Resolver-map).
+
+This will merge with the existing resolvers in core and from previous plugins.
+
+### hooks
+
+```js
+{
+  RootMutation: {
+    createPerson: {
+      post: async (obj, args, {plugins: {Slack}}, info, person) {
+        if (!person) {
+          return person;
+        }
+
+        await Slack.notify(`A new person just was created with name ${person.name}`);
+
+        return person;
+      }
+    }
+  }
+}
+```
+
+Hooks here are pretty special, for each resolver field, you can specify a
+pre/post hook that will execute pre and post field resolution.
+
+If your post function accepts four parameters, then it can modify the field
+result. It is *required* that the function resolves a promise (or returns) with
+the modified value or simply the original if you didn't modify it.
+
+### setupFunctions
+
+```js
+setupFunctions: {
+  leader: (options, args) => ({
+    leader: {
+      filter: (person) => person.place === 1
+    },
+  }),
+}
+```
+
+Setup functions allow you to create filters that control which pubsub.publish() events
+send data to the client. If the type in question contains args, clients may subscribe using those arguments to further filter their subscription.
+
+For more information, see the [Apollo Docs](https://github.com/apollographql/graphql-subscriptions).
+
+### tokenUserNotFound
+
+```js
+tokenUserNotFound: async ({jwt, token}) => {
+  let profile = await someExternalService(token);
+  if (!profile) {
+    return null;
+  }
+
+  let user = await UserModel.findOneAndUpdate({
+    id: profile.id
+  }, {
+    id: profile.id,
+    username: profile.username,
+    lowercaseUsername: profile.username.toLowerCase(),
+    roles: [],
+    profiles: []
+  }, {
+    setDefaultsOnInsert: true,
+    new: true,
+    upsert: true
+  });
+
+  return user;
+}
+```
+
+The `tokenUserNotFound` hook allows auth integrations to hook into the event
+when a valid token is provided but a user can't be found in the database that
+matches the provided id.
+
+The function is async, and should return the user object that was created in the
+database, or null if the user wasn't found. The `jwt` parameter of the object
+is the unpacked token, while `token` is the original jwt token string.
+
+### tags
+
+The tags hook allows a plugin to define tags that are code controlled (added
+or enabled by code). Below is an example pulled from the core off topic plugin
+on how to create a hook for the `OFF_TOPIC` name:
+
+```js
+[
+  {
+    name: 'OFF_TOPIC',
+    permissions: {
+      public: true,
+      self: true,
+      roles: []
+    },
+    models: ['COMMENTS'],
+    created_at: new Date()
+  }
+]
+```
+
+You can refer to `models/schema/tag.js` for the available schema to match when
+creating models to enable/disable specific features.
+
+### router
+
+```js
+(router) => {
+  router.get('/api/v1/people', (req, res) => {
+    res.json({people: [{name: 'Bob'}]});
+  });
+}
+```
+
+The Router hook allows you to create a function that accepts the base express
+router where you can mount any amount of middleware/routes to do any form of
+action needed by external applications.
+
+### passport
+
+```js
+const FacebookStrategy = require('passport-facebook').Strategy;
+const UsersService = require('services/users');
+const {ValidateUserLogin, HandleAuthPopupCallback} = require('services/passport');
+
+module.exports = {
+  passport(passport) {
+    passport.use(new FacebookStrategy({
+      clientID: process.env.TALK_FACEBOOK_APP_ID,
+      clientSecret: process.env.TALK_FACEBOOK_APP_SECRET,
+      callbackURL: `${process.env.TALK_ROOT_URL}/api/v1/auth/facebook/callback`,
+      passReqToCallback: true,
+      profileFields: ['id', 'displayName', 'picture.type(large)']
+    }, async (req, accessToken, refreshToken, profile, done) => {
+
+      let user;
+      try {
+        const { id, provider, displayName } = profile;
+        user = await UsersService.findOrCreateExternalUser(
+          req.context,
+          id,
+          provider,
+          displayName
+        );
+      } catch (err) {
+        return done(err);
+      }
+
+      return ValidateUserLogin(profile, user, done);
+    }));
+  },
+  router(router) {
+
+    // Note that we have to import the passport instance here, it is
+    // instantiated after all the strategies have been mounted.
+    const {passport} = require('services/passport');
+
+    /**
+     * Facebook auth endpoint, this will redirect the user immediately to facebook
+     * for authorization.
+     */
+    router.get('/facebook', passport.authenticate('facebook', {display: 'popup', authType: 'rerequest', scope: ['public_profile']}));
+
+    /**
+     * Facebook callback endpoint, this will send the user a html page designed to
+     * send back the user credentials upon successful login.
+     */
+    router.get('/facebook/callback', (req, res, next) => {
+
+      // Perform the facebook login flow and pass the data back through the opener.
+      passport.authenticate('facebook', HandleAuthPopupCallback(req, res, next))(req, res, next);
+    });
+  }
+};
+```
+
+### translations
+
+```js
+const path = require('path');
+
+module.exports = {
+  translations: path.join(__dirname, 'translations.yml'),
+};
+```
+
+Where the `translations.yml` contains:
+
+```yml
+en:
+  embedlink:
+    copy: "Copy Permalink"
+```
+
+Which overrides the copy for the `embedlink.copy` template. You can
+also provide other languages as well by using the correct language
+prefix.
+
+### websockets
+
+```js
+module.exports = {
+  websockets: {
+    onConnect: (connectionParams, connection) => {
+      // Do something with the connection params or connection, like
+      // logging it out, or incrementing a metric.
+    },
+    onDisconnect: (connection) => {
+      // Do something with the connection params or connection, like
+      // logging it out, or decrementing a metric.
+    },
+  },
+}
+```
+
+This `websockets` hook can be used to attach methods to the
+`onConnect` and `onDisconnect` events on a server. The intention for
+this hook is to allow administrators instrument the active websocket
+connections.
+
+### schemaLevelResolveFunction
+
+```js
+module.exports = {
+  schemaLevelResolveFunction: (root, args, ctx, info) => {
+    // The GraphQL Operation Name. Example: CoralEmbedStream_Embed
+    const name = info.operation.name !== null ? info.operation.name.value : null;
+    // Maybe increment a metric based on the operation name...
+
+    // You must _always_ return the root.
+    return root;
+  },
+};
+```
+
+The `schemaLevelResolveFunction` provides a function that is attached
+at the schema level, so that all queries that are made will go through. This
+can be used to create a better view of the graph landscape by creating metrics
+of resolved query names.
+
+## Full Example
+
+Contents of `plugins.json`:
+
+```json
+{
+  "server": [
+    "people"
+  ]
+}
+```
+
+Located in `plugins/people/index.js`:
+
+```js
+module.exports = {
+  typeDefs: `
+  enum COLOUR {
+    RED
+    BLUE
+  }
+
+  type Person {
+    name: String!
+    colour: COLOUR!
+  }
+
+  type RootMutation {
+    createPerson(name: String!): Person
+  }
+
+  type RootQuery {
+    people: [Person!]
+  }
+
+  type Subscription {
+    leader: Person
+  }
+  `,
+  context: {
+    Slack: () => ({
+      notify: (message) => {
+        // return a promise after we're done sending notifications.
+      }
+    })
+  },
+  loaders: ({user}) => ({
+    People: {
+      load: () => db.people.find({user})
+    }
+  }),
+  mutators: ({user}) => ({
+    People: {
+      create: (name) => {
+        return db.people.insert({user, name});
+      }
+    }
+  }),
+  resolvers: {
+    Person: {
+      name(obj, args, context) {
+        return obj.name;
+      },
+      colour(obj, args, context) {
+        // Bill likes the colour red, everyone else likes blue.
+        return obj.name === 'bill' ? 'RED' : 'BLUE';
+      }
+    },
+    RootQuery: {
+      people(obj, args, {loaders: {People}}) {
+        return People.load();
+      }
+    },
+    RootMutation: {
+      createPerson(obj, {name}, {mutators: {People}}) {
+        return People.create(name);
+      }
+    }
+  },
+  hooks: {
+    RootMutation: {
+      createPerson: {
+        post: async (obj, args, {plugins: {Slack}}, info, person) => {
+          if (!person) {
+            return person;
+          }
+
+          await Slack.notify(`A new person just was created with name ${person.name}`);
+
+          return person;
+        }
+      }
+    }
+  },
+  setupFunctions: {
+    leader: (options, args) => ({
+      leader: {
+        filter: (person) => person.place === 1
+      }
+    }
+  }
+};
+
+```