From 928f73b5655fa00427ebb6f145c2f4aa45ae36ea Mon Sep 17 00:00:00 2001
From: Jim LAURIE <jim@strapi.io>
Date: Wed, 18 Dec 2019 15:40:29 +0100
Subject: [PATCH] Add guide to init a third party client

---
 docs/.vuepress/config.js           |   1 +
 docs/3.0.0-beta.x/guides/client.md | 159 +++++++++++++++++++++++++++++
 2 files changed, 160 insertions(+)
 create mode 100644 docs/3.0.0-beta.x/guides/client.md

diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
index 9d2f6176dc..62d82777de 100644
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -202,6 +202,7 @@ module.exports = {
             '/3.0.0-beta.x/guides/external-data',
             '/3.0.0-beta.x/guides/custom-data-response',
             '/3.0.0-beta.x/guides/custom-admin',
+            '/3.0.0-beta.x/guides/client',
             '/3.0.0-beta.x/guides/draft',
             '/3.0.0-beta.x/guides/slug',
             '/3.0.0-beta.x/guides/webhooks',
diff --git a/docs/3.0.0-beta.x/guides/client.md b/docs/3.0.0-beta.x/guides/client.md
new file mode 100644
index 0000000000..fadf356d04
--- /dev/null
+++ b/docs/3.0.0-beta.x/guides/client.md
@@ -0,0 +1,159 @@
+# Setup a third party client
+
+This guide will explain how to setup a connection with a tiers client and use it everywhere in your code.
+
+In our example we will use the GitHub Node.JS client [OctoKit REST.js](https://github.com/octokit/rest.js/).
+
+This guide could also be used to setup an Axios client instance.
+
+## Installation
+
+First you will have to install the client node_module in your application by running one of the following command.
+
+:::: tabs
+
+::: tab yarn
+`yarn add @octokit/rest`
+:::
+
+::: tab npm
+`npm install @octokit/rest`
+:::
+
+::::
+
+## Create a hook
+
+To init the client, we will use [Strapi hooks system](../concepts/hooks.md). Hooks let you add new features in your Strapi application.
+
+Hooks are loaded one time, at the server start.
+
+Lets create our GitHub hook.
+
+**Path —** `./hooks/github/index.js`
+
+```js
+module.exports = strapi => {
+  const hook = {
+    initialize: async () => {
+      console.log('my hook is loaded');
+    },
+  };
+
+  return hook;
+};
+```
+
+When the hook is created, we have to enable it to say to Strapi to use this hook.
+
+**Path —** `./config/hook.json`
+
+```json
+{
+  ...
+  "github": {
+    "enabled": true
+  }
+}
+```
+
+Now you can start your application, you should see a log `my hook is loaded` in your terminal.
+
+## Initialize the client
+
+First lets update the config file to add your [GitHub token](https://github.com/settings/tokens).
+By following the [documentation](https://octokit.github.io/rest.js/#authentication) you will also find the way to use GitHub applications.
+
+**Path —** `./config/hook.json`
+
+```json
+{
+  ...
+  "github": {
+    "enabled": true,
+    "token": "bf78d4fc3c1767019870476d6d7cc8961383d80f"
+  }
+}
+```
+
+Now we have to load the GitHub client.
+
+**Path —** `./hooks/github/index.js`
+
+```js
+const GitHubAPI = require('@octokit/rest');
+
+module.exports = strapi => {
+  const hook = {
+    initialize: async () => {
+      const { token } = strapi.config.hook.github;
+
+      strapi.github = new GitHubAPI({
+        userAgent: `${strapi.config.info.name} v${strapi.config.info.version}`,
+        auth: `token ${token}`,
+      });
+    },
+  };
+
+  return hook;
+};
+```
+
+And here it is.
+
+You can now use `strapi.github` everywhere in your code to use the GitHub client.
+
+To simply test if it works, lets update the `bootstrap.js` function to log your GitHub profile.
+
+**Path —** `./config/functions/bootstrap.js`
+
+```js
+module.exports = async () => {
+  const data = await strapi.github.users.getAuthenticated();
+  console.log(data);
+};
+```
+
+Restart your server and you should see your GitHub profile data.
+
+## Configs by environment
+
+You would probably want specific configurations for development and production environment.
+
+To do so, we will update some configurations.
+
+You have to cut your `github` configs from `./config/hook.json` to set them in `./config/environments/development.json`.
+
+And in your GitHub hook, you will have to replace `strapi.config.hook.github` by `strapi.config.currentEnvironment.github` to access to the configs.
+
+**Path —** `./config/environments/development.json`
+
+```json
+{
+  "github": {
+    "enabled": true,
+    "token": "806506ab855a94e8608148315eeb39a44c29aee1"
+  }
+}
+```
+
+**Path —** `./hooks/github/inde.js`
+
+```js
+const GitHubAPI = require('@octokit/rest');
+
+module.exports = strapi => {
+  const hook = {
+    initialize: async () => {
+      const { token } = strapi.config.currentEnvironment.github;
+
+      strapi.github = new GitHubAPI({
+        userAgent: `${strapi.config.info.name} v${strapi.config.info.version}`,
+        auth: `token ${token}`,
+      });
+    },
+  };
+
+  return hook;
+};
+```