[NEW] GraphQL Documentation (RocketChat#849)

* init GraphQL Documentation

* GraphQL API Documentation

README.md

@@ -1,4 +1,4 @@
----
+Guides for developing and modifying Rocket.Chat's code---
 layout: home
 permalink: /index.html
 ---

_data/projects.yml

@@ -48,6 +48,7 @@
     Rest API: rest-api/
     Realtime API: realtime-api/
     Livechat API: livechat-api/
+    GraphQL API: graphql-api/
 
 -
   name: Bots

_data/toc.yml

@@ -419,6 +419,10 @@
       - Offset and Count and Sort Info
       - Query and Fields Info
       - Personal Access Tokens
+    - GraphQL API:
+      - Authentication
+      - Schema
+      - Subscription
     - Schema Definition
     - Testing
     - Troubleshooting

contributing/documentation/documentation-map/README.md

@@ -439,6 +439,10 @@ Here you can also find what articles are incomplete and missing.
         - Colors
         - Components
         - Themes
+        - GraphQL API:
+            - Authentication
+            - Schema
+            - Subscription
 - Bots:
     - Bots FAQ
     - Bots Architecture

developer-guides/README.md

@@ -6,6 +6,7 @@
 - [Branches and Releases](branches-and-releases/)
 - [Livechat API](livechat-api/)
 - [REST API](rest-api/)
+- [GraphQL API](graphql-api/)
 - [Developing Rocket.Chat Apps](developing-apps)
 - [Iframe Integration](iframe-integration/)
 - [Realtime API](realtime-api/)

developer-guides/graphql-api/README.md

@@ -0,0 +1,13 @@
+# GraphQL API
+
+Rocket.Chat now supports a GraphQL API.
+> **This API is a work in progress, so feel free to test, ask us questions, and submit Pull Requests!**
+
+The administrator must enable the GraphQL API in the admin panel (`General` -> `GraphQL API`).
+After that, you are able to use the GraphQL API, under `/api/graphql` endpoint.
+
+Here are some links that will be useful for the use of Rocket.Chat GraphQL API
+
+[Authentication](authentication/) <br/>
+[Schema](schema/) <br/>
+[Subscription](subscription/)

developer-guides/graphql-api/authentication/README.md

@@ -0,0 +1,78 @@
+# GraphQL API Authentication
+
+**Note**
+
+> To be able to use the GraphQL API, a login by GraphQL is needed (Tokens provided by REST API are different from the tokens of the GraphQL API).
+
+You can login with GraphQL through `loginWithPassword` mutation, and then with the `accessToken` in hand, you should
+put it in the headers of your requests against Rocket.Chat GraphQL API (`Authorization: MyAccessToken`).
+
+Below are some examples of how the login structure works with username and password:
+
+You can send the requests with GraphQL Queries with `POST` http method. You can send the query over http request, or you can use any GraphQL lib for client side.
+
+## Username and Password
+
+```
+mutation login {
+    loginWithPassword(user: "myrocketchatuser", password: "mypassword") {
+        user {
+            username,
+            email,
+            id
+        },
+        tokens {
+            accessToken
+        }
+    }
+}
+```
+
+## Email and Password
+
+```
+mutation login {
+    loginWithPassword(user: "", userFields: {email: "[email protected]"}, password: "mypassword") {
+        user {
+            username,
+            email,
+            id
+        },
+        tokens {
+            accessToken
+        }
+    }
+}
+```
+
+## Grant
+
+The main idea behind this package was to allow the external, stand-alone applications (i.e. PWA) to be able to easily use OAuth authentication that is integrated with
+accounts system used in Rocket.Chat. <br/>
+
+The flow:
+
+1. User requests an authentication via some OAuth Provider. Let's use Google and PWA as an example.
+2. An app redirects him to a URL handled by Grant. `e.g. http://localhost:3000/_oauth_apps/connect/google/pwa`.
+3. The URL is being interpreted so Grant knows which provider should be used to authenticate a user and what is the app we want to redirect him after auth completes.
+4. Authentication happens
+5. OAuth Provider sends client back to Grant, according to predefined callback url.
+6. Grant handles the response and redirects a user to the starting point with some data that allows the application to log user in.
+
+What's the most important, every external application that has been registered in Grant ecosystem shares the same OAuth credentials for each provider.
+For example, imagine we have two PWA applications, React and Angular versions. We don't need to provide two sets of credentials for Google OAuth, we only use one and flow stays the same.
+
+Beside registering providers, Grant allows to enable and disable them whenever you want to.
+Imagine a situation where Rocket.Chat, the main Meteor application exposes only Google OAuth but we already defined Facebook and GitHub in Grant. You can just turn them off.
+
+Grant also exposes an endpoint that shows which providers are enabled and used so you can make only those visible in your application.
+
+We also created a few packages to have something to start with: <br/>
+[`rocketchat:grant-facebook`](https://github.com/RocketChat/Rocket.Chat/tree/develop/packages/rocketchat-grant-facebook) <br/>
+[`rocketchat:grant-google`](https://github.com/RocketChat/Rocket.Chat/tree/develop/packages/rocketchat-grant-google) <br/>
+[`rocketchat:grant-github`](https://github.com/RocketChat/Rocket.Chat/tree/develop/packages/rocketchat-grant-github) <br/>
+
+If anyone wants to contribute by adding more grants, here is a [npm package with several integrations](https://github.com/simov/grant#150-supported-providers--oauth-playground)
+
+
+

developer-guides/graphql-api/schema/README.md

@@ -0,0 +1,13 @@
+# GraphQL API Schema
+
+To see the GraphQL schema of the Rocket.Chat GraphQL API, you should use some GraphQL graphical tool. <br/>
+These tools are able to show the schema, using the [Instropection tool](https://graphql.org/learn/introspection/) of GraphQL.<br/>
+You can use the instrospection queries to show the schema, but by a graphical tool is easier.<br/>
+Below we have some options of tools, and where you can see the schema in each of them.
+
+**Graphical Tools:**
+
+[GraphQL Playground](https://github.com/prisma/graphql-playground) (You can see the schema by clicking on the green button("schema") on the right side). <br/>
+[Altair GraphQL](https://altair.sirmuel.design/) (You can see the schema by clicking on the "Docs" button, which is on the left side of the "Send Request" button). <br/>
+`GraphiQL` (GraphiQL is a tool provided by the API itself, just access the `{YOUR_HOST}/graphiql` endpoint and make sure the server is in **development** mode.
+You can see the schema by clicking the "Docs" button in the upper right corner).

developer-guides/graphql-api/subscription/README.md

@@ -0,0 +1,8 @@
+# GraphQL API Subscription
+
+You can subscribe (Websocket protocol) to listen to events, by a GraphQL subscription.
+You should listen the event on the same port defined in the admin panel, in the GraphQL subscription port field. (`General` -> `GrahQL API` -> `GraphQL Subscription Port`)
+
+**Events available:**
+
+ `chatMessageAdded`