Skip to content

Commit 3341e7b

Browse files
MoumoulsTomWFox
Moumouls
and
TomWFox
committed
GraphQL Docs for Parse Server 3.10.0 (#688)
* wip * wip * first version * Add nested Query & Mutation * Update _includes/graphql/users.md Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Update _includes/graphql/classes.md Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Update _includes/graphql/relay.md Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Update _includes/graphql/files.md Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Update _includes/graphql/files.md Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Update _includes/graphql/getting-started.md Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Update _includes/graphql/relay.md Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Update _includes/graphql/graphql.md Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Update _includes/graphql/relay.md Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Update _includes/graphql/relay.md Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Update _includes/graphql/getting-started.md Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Update _includes/graphql/graphql.md Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Update _includes/graphql/objects.md Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Update _includes/graphql/objects.md Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Update _includes/graphql/queries.md Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Update _includes/graphql/objects.md Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Update _includes/graphql/objects.md Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Update _includes/graphql/queries.md Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Fix * Add Relational Query * Apply suggestions from code review Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Update _includes/graphql/queries.md Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Update _includes/graphql/queries.md Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Apply suggestions from code review Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Wip optimization * GraphQL Api second position + remove beta + fix conflicts * Apply suggestions from code review Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Update _includes/graphql/optimization.md Co-Authored-By: Tom Fox <13188249+TomWFox@users.noreply.github.com> * Update queries.md * minor changes * change from previous review comment * Update objects.md * Update users.md * Update graphql.md * Update queries.md * change from Omair review * changes from earlier review * Update optimization.md Co-authored-by: Tom Fox <13188249+TomWFox@users.noreply.github.com>
1 parent 38ba0f6 commit 3341e7b

17 files changed

+2126
-1069
lines changed

‎_includes/graphql/api-doc.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# API Doc
2+
3+
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.
4+
5+
```bash
6+
$ npm install -g parse-server mongodb-runner
7+
$ mongodb-runner start
8+
$ parse-server --appId APPLICATION_ID --masterKey MASTER_KEY --databaseURI mongodb://localhost/test --mountGraphQL --mountPlayground
9+
```
10+
11+
Visit your [Local GraphQL Playground](http://localhost:1337/playground)
12+
13+
<img alt="GraphQL Playground" data-echo="{{ '/assets/images/graphql/graphql-playground.png' | prepend: site.baseurl }}"/>

‎_includes/graphql/classes.md

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Classes
2+
3+
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:
4+
```js
5+
// Header
6+
{
7+
"X-Parse-Application-Id": "APPLICATION_ID",
8+
"X-Parse-Master-Key": "MASTER_KEY"
9+
}
10+
```
11+
12+
```graphql
13+
# GraphQL
14+
mutation createGameScoreClass {
15+
createClass(
16+
input: {
17+
clientMutationId: "anFrontId"
18+
name: "GameScore"
19+
schemaFields: {
20+
addStrings: [{ name: "playerName" }]
21+
addNumbers: [{ name: "score" }]
22+
addBooleans: [{ name: "cheatMode" }]
23+
}
24+
}
25+
) {
26+
clientMutationId
27+
class {
28+
name
29+
schemaFields {
30+
name
31+
__typename
32+
}
33+
}
34+
}
35+
}
36+
```
37+
```js
38+
// Response
39+
{
40+
"data": {
41+
"createClass": {
42+
"clientMutationId": "anFrontId",
43+
"class": {
44+
"name": "GameScore",
45+
"schemaFields": [
46+
{
47+
"name": "objectId",
48+
"__typename": "SchemaStringField"
49+
},
50+
{
51+
"name": "updatedAt",
52+
"__typename": "SchemaDateField"
53+
},
54+
{
55+
"name": "createdAt",
56+
"__typename": "SchemaDateField"
57+
},
58+
{
59+
"name": "playerName",
60+
"__typename": "SchemaStringField"
61+
},
62+
{
63+
"name": "score",
64+
"__typename": "SchemaNumberField"
65+
},
66+
{
67+
"name": "cheatMode",
68+
"__typename": "SchemaBooleanField"
69+
},
70+
{
71+
"name": "ACL",
72+
"__typename": "SchemaACLField"
73+
}
74+
]
75+
}
76+
}
77+
}
78+
}
79+
```
80+
81+
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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Customisation
22

3-
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.
3+
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.
44

55
## Configuration
66

@@ -67,7 +67,7 @@ interface ParseGraphQLConfiguration {
6767
find?: boolean;
6868
};
6969

70-
// By default, all write mutation types are
70+
// By default, all write mutation types are
7171
// exposed for all included classes. Use this to disable
7272
// the available mutation types for this class.
7373
mutation?: {

‎_includes/graphql/files.md

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Files
2+
3+
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).
4+
5+
## Add a File field
6+
First of all we will update our `GameScore` class with a `screenshot` field of type `File`.
7+
8+
```js
9+
// Header
10+
{
11+
"X-Parse-Application-Id": "APPLICATION_ID",
12+
"X-Parse-Master-Key": "MASTER_KEY"
13+
}
14+
```
15+
```graphql
16+
# GraphQL
17+
mutation updateGameScoreClass {
18+
updateClass(
19+
input: {
20+
name: "GameScore",
21+
schemaFields: {
22+
addFiles: [{ name: "screenshot" }]
23+
}
24+
}
25+
) {
26+
class {
27+
name
28+
}
29+
}
30+
}
31+
```
32+
```js
33+
// Response
34+
{
35+
"data": {
36+
"updateClass": {
37+
"class": {
38+
"name": "GameScore"
39+
}
40+
}
41+
}
42+
}
43+
```
44+
45+
## Create and add File
46+
47+
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.
48+
49+
```js
50+
// Header
51+
{
52+
"X-Parse-Application-Id": "APPLICATION_ID",
53+
"X-Parse-Master-Key": "MASTER_KEY" // (optional)
54+
}
55+
```
56+
```graphql
57+
# GraphQL
58+
# $file is a GraphQL Variable, see https://github.com/jaydenseric/apollo-upload-client
59+
mutation createFile($file: Upload!) {
60+
createFile(input: { upload: $file }) {
61+
fileInfo {
62+
name
63+
url
64+
}
65+
}
66+
}
67+
```
68+
```js
69+
// Response
70+
{
71+
"data": {
72+
"createFile": {
73+
"fileInfo": {
74+
"name": "6a4d43c3f0512bcb6bf05b6b0e7db47d_file.png",
75+
"url": "http://localhost:1337/graphq/files/APPLICATION_ID/6a4d43c3f0512bcb6bf05b6b0e7db47d_file.png"
76+
}
77+
}
78+
}
79+
}
80+
```
81+
82+
Then add the file to a new `GameScore` object.
83+
```js
84+
// Header
85+
{
86+
"X-Parse-Application-Id": "APPLICATION_ID",
87+
"X-Parse-Master-Key": "MASTER_KEY" // (optional)
88+
}
89+
```
90+
```graphql
91+
# GraphQL
92+
mutation createGameScore {
93+
createGameScore(
94+
input: {
95+
fields: {
96+
playerName: "John"
97+
screenshot: {
98+
__type: "File",
99+
name: "6a4d43c3f0512bcb6bf05b6b0e7db47d_file.png"
100+
url: "http://localhost:1337/graphq/files/APPLICATION_ID/6a4d43c3f0512bcb6bf05b6b0e7db47d_file.png"
101+
}
102+
}
103+
}
104+
) {
105+
gameScore {
106+
screenshot {
107+
name
108+
url
109+
}
110+
}
111+
}
112+
}
113+
```
114+
```js
115+
// Response
116+
{
117+
"data": {
118+
"createGameScore": {
119+
"gameScore": {
120+
"screenshot": {
121+
"name": "6a4d43c3f0512bcb6bf05b6b0e7db47d_file.png",
122+
"url": "http://localhost:1337/graphq/files/APPLICATION_ID/6a4d43c3f0512bcb6bf05b6b0e7db47d_file.png"
123+
}
124+
}
125+
}
126+
}
127+
}
128+
```

‎_includes/graphql/getting-started.md

Lines changed: 28 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,62 +1,55 @@
11
# Getting Started
22

3-
[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.
3+
[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.
44

5+
## Fast launch
56
The easiest way to run the Parse GraphQL Server is using the CLI:
67

78
```bash
89
$ npm install -g parse-server mongodb-runner
910
$ mongodb-runner start
10-
$ parse-server --appId APPLICATION_ID --masterKey MASTER_KEY --databaseURI mongodb://localhost/test --publicServerURL http://localhost:1337/parse --mountGraphQL --mountPlayground
11+
$ parse-server --appId APPLICATION_ID --masterKey MASTER_KEY --databaseURI mongodb://localhost/test --mountGraphQL --mountPlayground
1112
```
1213

1314
Notes:
1415
* 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.
15-
* ⚠️ 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.
16-
* ⚠️ 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.
16+
* ⚠️ 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)
1717

1818
After running the CLI command, you should have something like this in your terminal:
1919

20-
<img alt="Parse GraphQL Server" data-echo="{{ '/assets/images/graphql/parse-graphql-server.png' | prepend: site.baseurl }}"/>
20+
```sh
21+
...
22+
[35071] parse-server running on http://localhost:1337/parse
23+
[35071] GraphQL running on http://localhost:1337/graphql
24+
[35071] Playground running on http://localhost:1337/playground
25+
```
2126

2227
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.
2328

2429
<img alt="GraphQL Playground" data-echo="{{ '/assets/images/graphql/graphql-playground.png' | prepend: site.baseurl }}"/>
2530

26-
## Using Docker
27-
28-
You can also run the Parse GraphQL API inside a Docker container:
29-
30-
```bash
31-
$ git clone https://github.com/parse-community/parse-server
32-
$ cd parse-server
33-
$ docker build --tag parse-server .
34-
$ docker run --name my-mongo -d mongo
35-
$ 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
36-
```
37-
38-
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.
39-
40-
⚠️ 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.
41-
4231
## Using Express.js
4332

4433
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:
4534

46-
```bash
35+
```sh
4736
$ mkdir my-app
4837
$ cd my-app
38+
$ npm init
4939
$ npm install parse-server express --save
5040
```
5141

5242
Then, create an `index.js` file with the following content:
5343

5444
```js
45+
// index.js
5546
const express = require('express');
5647
const { default: ParseServer, ParseGraphQLServer } = require('parse-server');
5748

49+
// Create express app
5850
const app = express();
5951

52+
// Create a Parse Server Instance
6053
const parseServer = new ParseServer({
6154
databaseURI: 'mongodb://localhost:27017/test',
6255
appId: 'APPLICATION_ID',
@@ -65,6 +58,7 @@ const parseServer = new ParseServer({
6558
publicServerURL: 'http://localhost:1337/parse'
6659
});
6760

61+
// Create the GraphQL Server Instance
6862
const parseGraphQLServer = new ParseGraphQLServer(
6963
parseServer,
7064
{
@@ -73,10 +67,14 @@ const parseGraphQLServer = new ParseGraphQLServer(
7367
}
7468
);
7569

76-
app.use('/parse', parseServer.app); // (Optional) Mounts the REST API
77-
parseGraphQLServer.applyGraphQL(app); // Mounts the GraphQL API
78-
parseGraphQLServer.applyPlayground(app); // (Optional) Mounts the GraphQL Playground - do NOT use in Production
70+
// (Optional) Mounts the REST API
71+
app.use('/parse', parseServer.app);
72+
// Mounts the GraphQL API using graphQLPath: '/graphql'
73+
parseGraphQLServer.applyGraphQL(app);
74+
// (Optional) Mounts the GraphQL Playground - do NOT use in Production
75+
parseGraphQLServer.applyPlayground(app);
7976

77+
// Start the server
8078
app.listen(1337, function() {
8179
console.log('REST API running on http://localhost:1337/parse');
8280
console.log('GraphQL API running on http://localhost:1337/graphql');
@@ -86,22 +84,22 @@ app.listen(1337, function() {
8684

8785
And finally start your app:
8886

89-
```bash
87+
```sh
9088
$ npx mongodb-runner start
9189
$ node index.js
9290
```
9391

9492
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.
9593

96-
⚠️ 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.
94+
⚠️ 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).
9795

9896
## Running Parse Dashboard
9997

100-
[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.
98+
[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.
10199

102100
The easiest way to run the Parse Dashboard is through its CLI:
103101

104-
```bash
102+
```sh
105103
$ npm install -g parse-dashboard
106104
$ parse-dashboard --dev --appId APPLICATION_ID --masterKey MASTER_KEY --serverURL "http://localhost:1337/parse" --graphQLServerURL "http://localhost:1337/graphql" --appName MyAppName
107105
```
@@ -110,4 +108,4 @@ After starting the dashboard, you can visit [http://0.0.0.0:4040/apps/MyAppName/
110108

111109
<img alt="Parse Dashboard GraphQL Playground" data-echo="{{ '/assets/images/graphql/dashboard-graphql-playground.png' | prepend: site.baseurl }}"/>
112110

113-
To learn more about Parse Dashboard and its setup options, please visit [Parse Dashboard Repository](https://github.com/parse-community/parse-dashboard).
111+
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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# GraphQL
2+
3+
Before continuing, it is recommended to study some of the GraphQL documentation:
4+
5+
A GraphQL API contains 3 main concepts:
6+
* `Query`: Fetch data
7+
* `Mutation`: Create or update data
8+
* `Subscription`: Listen for data changes
9+
10+
## Learn Query & Mutation
11+
To learn how to query data and execute operation on a GraphQL API [consult the official documentation](https://graphql.org/learn/queries/).

0 commit comments

Comments
 (0)