GraphQL Docs for Parse Server 3.10.0

_includes/graphql/api-doc.md

@@ -0,0 +1,13 @@
+# API Doc
+
+GraphQL is a self documented API, to learn all available operations, it's recommended to start the Parse GraphQL Server and visit the Docs tab on the GraphQL Playground.
+
+```bash
+$ npm install -g parse-server mongodb-runner
+$ mongodb-runner start
+$ parse-server --appId APPLICATION_ID --masterKey MASTER_KEY --databaseURI mongodb://localhost/test --mountGraphQL --mountPlayground
+```
+
+Visit your [Local GraphQL Playground](http://localhost:1337/playground)
+
+<img alt="GraphQL Playground" data-echo="{{ '/assets/images/graphql/graphql-playground.png' | prepend: site.baseurl }}"/>

_includes/graphql/classes.md

@@ -0,0 +1,81 @@
+# Classes
+
+Since your application does not have a schema yet, you can use the `createClass` mutation to create your first class through the GraphQL API. Run the following:
+```js
+// Header
+{
+  "X-Parse-Application-Id": "APPLICATION_ID",
+  "X-Parse-Master-Key": "MASTER_KEY"
+}
+```
+
+```graphql
+# GraphQL
+mutation createGameScoreClass {
+  createClass(
+    input: {
+      clientMutationId: "anFrontId"
+      name: "GameScore"
+      schemaFields: {
+        addStrings: [{ name: "playerName" }]
+        addNumbers: [{ name: "score" }]
+        addBooleans: [{ name: "cheatMode" }]
+      }
+    }
+  ) {
+    clientMutationId
+    class {
+      name
+      schemaFields {
+        name
+        __typename
+      }
+    }
+  }
+}
+```
+```js
+// Response
+{
+  "data": {
+    "createClass": {
+      "clientMutationId": "anFrontId",
+      "class": {
+        "name": "GameScore",
+        "schemaFields": [
+          {
+            "name": "objectId",
+            "__typename": "SchemaStringField"
+          },
+          {
+            "name": "updatedAt",
+            "__typename": "SchemaDateField"
+          },
+          {
+            "name": "createdAt",
+            "__typename": "SchemaDateField"
+          },
+          {
+            "name": "playerName",
+            "__typename": "SchemaStringField"
+          },
+          {
+            "name": "score",
+            "__typename": "SchemaNumberField"
+          },
+          {
+            "name": "cheatMode",
+            "__typename": "SchemaBooleanField"
+          },
+          {
+            "name": "ACL",
+            "__typename": "SchemaACLField"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+Parse Server learned from the first class that you created and now you have the `GameScore` class in your schema. You can now start using the automatically generated operations!

_includes/graphql/customisation.md

@@ -1,6 +1,6 @@
 # Customisation
 
-Although we automtically generate a GraphQL schema based on your Parse Server database, we have provided a number of ways in which to configure and extend this schema.
+Although we automatically generate a GraphQL schema based on your Parse Server database, we have provided a number of ways in which to configure and extend this schema.
 
 ## Configuration
 
@@ -67,7 +67,7 @@ interface ParseGraphQLConfiguration {
       find?: boolean;
     };
 
-    // By default, all write mutation types are 
+    // By default, all write mutation types are
     // exposed for all included classes. Use this to disable
     // the available mutation types for this class.
     mutation?: {

_includes/graphql/files.md

@@ -0,0 +1,128 @@
+# Files
+
+The GraphQL API supports file upload via [GraphQL Upload](https://github.com/jaydenseric/graphql-upload), to send a `File` through `GraphQL` it's recommended to use the [Apollo Upload Client](https://github.com/jaydenseric/apollo-upload-client).
+
+## Add a File field
+First of all we will update our `GameScore` class with a `screenshot` field of type `File`.
+
+```js
+// Header
+{
+  "X-Parse-Application-Id": "APPLICATION_ID",
+  "X-Parse-Master-Key": "MASTER_KEY"
+}
+```
+```graphql
+# GraphQL
+mutation updateGameScoreClass {
+  updateClass(
+    input: { 
+      name: "GameScore",
+      schemaFields: { 
+        addFiles: [{ name: "screenshot" }]
+      }
+    }
+  ) {
+    class {
+      name
+    }
+  }
+}
+```
+```js
+// Response
+{
+  "data": {
+    "updateClass": {
+      "class": {
+        "name": "GameScore"
+      }
+    }
+  }
+}
+```
+
+## Create and add File
+
+Currently the GraphQL API does not support nested mutation for the `File` type, so we need to send the file and then create/update the `GameScore` object with the returned information.
+
+```js
+// Header
+{
+  "X-Parse-Application-Id": "APPLICATION_ID",
+  "X-Parse-Master-Key": "MASTER_KEY" // (optional)
+}
+```
+```graphql
+# GraphQL
+# $file is a GraphQL Variable, see https://github.com/jaydenseric/apollo-upload-client
+mutation createFile($file: Upload!) {
+  createFile(input: { upload: $file }) {
+    fileInfo {
+      name
+      url
+    }
+  }
+}
+```
+```js
+// Response
+{
+  "data": {
+    "createFile": {
+      "fileInfo": {
+        "name": "6a4d43c3f0512bcb6bf05b6b0e7db47d_file.png",
+        "url": "http://localhost:1337/graphq/files/APPLICATION_ID/6a4d43c3f0512bcb6bf05b6b0e7db47d_file.png"
+      }
+    }
+  }
+}
+```
+
+Then add the file to a new `GameScore` object.
+```js
+// Header
+{
+  "X-Parse-Application-Id": "APPLICATION_ID",
+  "X-Parse-Master-Key": "MASTER_KEY" // (optional)
+}
+```
+```graphql
+# GraphQL
+mutation createGameScore {
+  createGameScore(
+    input: {
+      fields: {
+        playerName: "John"
+        screenshot: {
+          __type: "File",
+          name: "6a4d43c3f0512bcb6bf05b6b0e7db47d_file.png"
+          url: "http://localhost:1337/graphq/files/APPLICATION_ID/6a4d43c3f0512bcb6bf05b6b0e7db47d_file.png"
+        }
+      }
+    }
+  ) {
+    gameScore {
+      screenshot {
+        name
+        url
+      }
+    }
+  }
+}
+```
+```js
+// Response
+{
+  "data": {
+    "createGameScore": {
+      "gameScore": {
+        "screenshot": {
+          "name": "6a4d43c3f0512bcb6bf05b6b0e7db47d_file.png",
+          "url": "http://localhost:1337/graphq/files/APPLICATION_ID/6a4d43c3f0512bcb6bf05b6b0e7db47d_file.png"
+        }
+      }
+    }
+  }
+}
+```

_includes/graphql/getting-started.md

@@ -1,62 +1,55 @@
 # Getting Started
 
-[GraphQL](https://graphql.org/), developed by Facebook, is an open-source data query and manipulation language for APIs. In addition to the traditional [REST API](/rest/guide/), Parse Server automatically generates a GraphQL API based on your current application schema.
+[GraphQL](https://graphql.org/), developed by Facebook, is an open-source data query and manipulation language for APIs. In addition to the traditional [REST API](/rest/guide/), Parse Server automatically generates a GraphQL API based on your current application schema. Specifically, Parse has opted for the [Relay](https://relay.dev/docs/en/introduction-to-relay) specification in-line with industry best-practices.
 
+## Fast launch
 The easiest way to run the Parse GraphQL Server is using the CLI:
 
 ```bash
 $ npm install -g parse-server mongodb-runner
 $ mongodb-runner start
-$ parse-server --appId APPLICATION_ID --masterKey MASTER_KEY --databaseURI mongodb://localhost/test --publicServerURL http://localhost:1337/parse --mountGraphQL --mountPlayground
+$ parse-server --appId APPLICATION_ID --masterKey MASTER_KEY --databaseURI mongodb://localhost/test --mountGraphQL --mountPlayground
 ```
 
 Notes:
 * Run `parse-server --help` or refer to [Parse Server Options](https://parseplatform.org/parse-server/api/master/ParseServerOptions.html) for a complete list of Parse Server configuration options.
-* ⚠️ Please do not use `--mountPlayground` option in production as anyone could access your API Playground and read or change your application's data. [Parse Dashboard](#running-parse-dashboard) has a built-in GraphQL Playground and it is the recommended option for production apps.
-* ⚠️ The Parse GraphQL ```beta``` implementation is fully functional but discussions are taking place on how to improve it. So new versions of Parse Server can bring breaking changes to the current API.
+* ⚠️ Please do not use `--mountPlayground` option in production as anyone could access your API Playground and read or change your application's data. [Parse Dashboard](#running-parse-dashboard) has a built-in GraphQL Playground and it is the recommended option for production apps. If you want to secure your API in production take a look at [Class Level Permissions](/js/guide/#class-level-permissions)
 
 After running the CLI command, you should have something like this in your terminal:
 
-<img alt="Parse GraphQL Server" data-echo="{{ '/assets/images/graphql/parse-graphql-server.png' | prepend: site.baseurl }}"/>
+```sh
+...
+[35071] parse-server running on http://localhost:1337/parse
+[35071] GraphQL running on http://localhost:1337/graphql
+[35071] Playground running on http://localhost:1337/playground
+```
 
 Since you have already started your Parse GraphQL Server, you can now visit [http://localhost:1337/playground](http://localhost:1337/playground) in your web browser to start playing with your GraphQL API.
 
 <img alt="GraphQL Playground" data-echo="{{ '/assets/images/graphql/graphql-playground.png' | prepend: site.baseurl }}"/>
 
-## Using Docker
-
-You can also run the Parse GraphQL API inside a Docker container:
-
-```bash
-$ git clone https://github.com/parse-community/parse-server
-$ cd parse-server
-$ docker build --tag parse-server .
-$ docker run --name my-mongo -d mongo
-$ docker run --name my-parse-server --link my-mongo:mongo -p 1337:1337 -d parse-server --appId APPLICATION_ID --masterKey MASTER_KEY --databaseURI mongodb://mongo/test --publicServerURL http://localhost:1337/parse --mountGraphQL --mountPlayground
-```
-
-After starting the server, you can visit [http://localhost:1337/playground](http://localhost:1337/playground) in your browser to start playing with your GraphQL API.
-
-⚠️ Please do not use `--mountPlayground` option in production as anyone could access your API Playground and read or change your application's data. [Parse Dashboard](#running-parse-dashboard) has a built-in GraphQL Playground and it is the recommended option for production apps.
-
 ## Using Express.js
 
 You can also mount the GraphQL API in an Express.js application together with the REST API or solo. You first need to create a new project and install the required dependencies:
 
-```bash
+```sh
 $ mkdir my-app
 $ cd my-app
+$ npm init
 $ npm install parse-server express --save
 ```
 
 Then, create an `index.js` file with the following content:
 
 ```js
+// index.js
 const express = require('express');
 const { default: ParseServer, ParseGraphQLServer } = require('parse-server');
 
+// Create express app
 const app = express();
 
+// Create a Parse Server Instance
 const parseServer = new ParseServer({
   databaseURI: 'mongodb://localhost:27017/test',
   appId: 'APPLICATION_ID',
@@ -65,6 +58,7 @@ const parseServer = new ParseServer({
   publicServerURL: 'http://localhost:1337/parse'
 });
 
+// Create the GraphQL Server Instance
 const parseGraphQLServer = new ParseGraphQLServer(
   parseServer,
   {
@@ -73,10 +67,14 @@ const parseGraphQLServer = new ParseGraphQLServer(
   }
 );
 
-app.use('/parse', parseServer.app); // (Optional) Mounts the REST API
-parseGraphQLServer.applyGraphQL(app); // Mounts the GraphQL API
-parseGraphQLServer.applyPlayground(app); // (Optional) Mounts the GraphQL Playground - do NOT use in Production
+// (Optional) Mounts the REST API
+app.use('/parse', parseServer.app);
+// Mounts the GraphQL API using graphQLPath: '/graphql'
+parseGraphQLServer.applyGraphQL(app);
+// (Optional) Mounts the GraphQL Playground - do NOT use in Production
+parseGraphQLServer.applyPlayground(app);
 
+// Start the server
 app.listen(1337, function() {
   console.log('REST API running on http://localhost:1337/parse');
   console.log('GraphQL API running on http://localhost:1337/graphql');
@@ -86,22 +84,22 @@ app.listen(1337, function() {
 
 And finally start your app:
 
-```bash
+```sh
 $ npx mongodb-runner start
 $ node index.js
 ```
 
 After starting the app, you can visit [http://localhost:1337/playground](http://localhost:1337/playground) in your browser to start playing with your GraphQL API.
 
-⚠️ Please do not mount the GraphQL Playground in production as anyone could access your API Playground and read or change your application's data. [Parse Dashboard](#running-parse-dashboard) has a built-in GraphQL Playground and it is the recommended option for production apps.
+⚠️ Please do not mount the GraphQL Playground in production as anyone could access your API Playground and read or change your application's data. [Parse Dashboard](#running-parse-dashboard) has a built-in GraphQL Playground and it is the recommended option for production apps. If you want to secure your API in production take a look at [Class Level Permissions](/js/guide/#class-level-permissions).
 
 ## Running Parse Dashboard
 
-[Parse Dashboard](https://github.com/parse-community/parse-dashboard) is a standalone dashboard for managing your Parse Server apps, including your objects' schema and data, logs, jobs, and push notifications. Parse Dashboard also has a built-in GraphQL Playground that you can use to play around with your auto-generated Parse GraphQL API. It is the recommended option for production applications.
+[Parse Dashboard](https://github.com/parse-community/parse-dashboard) is a standalone dashboard for managing your Parse Server apps, including your objects' schema and data, logs, jobs, CLPs, and push notifications. Parse Dashboard also has a built-in GraphQL Playground that you can use to play around with your auto-generated Parse GraphQL API. It is the recommended option for **production** applications.
 
 The easiest way to run the Parse Dashboard is through its CLI:
 
-```bash
+```sh
 $ npm install -g parse-dashboard
 $ parse-dashboard --dev --appId APPLICATION_ID --masterKey MASTER_KEY --serverURL "http://localhost:1337/parse" --graphQLServerURL "http://localhost:1337/graphql" --appName MyAppName
 ```
@@ -110,4 +108,4 @@ After starting the dashboard, you can visit [http://0.0.0.0:4040/apps/MyAppName/
 
 <img alt="Parse Dashboard GraphQL Playground" data-echo="{{ '/assets/images/graphql/dashboard-graphql-playground.png' | prepend: site.baseurl }}"/>
 
-To learn more about Parse Dashboard and its setup options, please visit [Parse Dashboard Repository](https://github.com/parse-community/parse-dashboard).
+To learn more about Parse Dashboard and its setup options, please visit the [Parse Dashboard Repository](https://github.com/parse-community/parse-dashboard).

_includes/graphql/graphql.md

@@ -0,0 +1,11 @@
+# GraphQL
+
+Before continuing, it is recommended to study some of the GraphQL documentation:
+
+A GraphQL API contains 3 main concepts:
+* `Query`: Fetch data
+* `Mutation`: Create or update data
+* `Subscription`: Listen for data changes
+
+## Learn Query & Mutation
+To learn how to query data and execute operation on a GraphQL API [consult the official documentation](https://graphql.org/learn/queries/).