Getting Started

GraphQL, developed by Facebook, is an open-source data query and manipulation language for APIs. In addition to the traditional REST API, Parse Server automatically generates a GraphQL API based on your current application schema. Specifically, Parse has opted for the Relay specification in-line with industry best-practices.

Fast launch

The easiest way to run the Parse GraphQL Server is using the CLI:

$ npm install -g parse-server mongodb-runner
$ mongodb-runner start
$ 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 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 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

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

...
[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 in your web browser to start playing with your GraphQL API.

GraphQL Playground

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:

$ mkdir my-app
$ cd my-app
$ npm init
$ npm install parse-server express --save

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

// 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',
  masterKey: 'MASTER_KEY',
  serverURL: 'http://localhost:1337/parse',
  publicServerURL: 'http://localhost:1337/parse'
});

// Create the GraphQL Server Instance
const parseGraphQLServer = new ParseGraphQLServer(
  parseServer,
  {
    graphQLPath: '/graphql',
    playgroundPath: '/playground'
  }
);

// (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');
  console.log('GraphQL Playground running on http://localhost:1337/playground');
});

And finally start your app:

$ npx mongodb-runner start
$ node index.js

After starting the app, you can visit 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 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.

Running Parse Dashboard

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:

$ 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

After starting the dashboard, you can visit http://0.0.0.0:4040/apps/MyAppName/api_console/graphql in your browser:

Parse Dashboard GraphQL Playground

To learn more about Parse Dashboard and its setup options, please visit the Parse Dashboard Repository.

Want to contribute to this doc? Edit this section.

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.

Want to contribute to this doc? Edit this section.

Relay

The Parse Server GraphQL API follows latest standards currently available for highly-scalable APIs and ambitious front-end projects.

The Parse Open Source Team choose to follow the GraphQL Server Relay Specification.

Relay is a JavaScript framework for building data-driven React applications powered by GraphQL, designed from the ground up to be easy to use, extensible and, most of all, performant. Relay accomplishes this with static queries and ahead-of-time code generation.

Later we will see some Relay concepts like: Node, Connection and Cursor.

Want to contribute to this doc? Edit this section.

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.

$ 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

GraphQL Playground

Want to contribute to this doc? Edit this section.

Health Check

Now that you have set up your GraphQL environment, it is time to run your first query. Execute the following code in your GraphQL Playground to check your API’s health:

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Master-Key": "MASTER_KEY"
}
# GraphQL
query healthy {
  health
}
// Response
{
  "data": {
    "health": true
  }
}
Want to contribute to this doc? Edit this section.

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:

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Master-Key": "MASTER_KEY"
}
# 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
      }
    }
  }
}
// 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!

Want to contribute to this doc? Edit this section.

Objects

Create

For each class in your application’s schema, Parse Server automatically generates a custom mutation for creating this class’ objects through the GraphQL API.

For example, if you have a class named GameScore in the schema, Parse Server automatically generates a new mutation called createGameScore, and you should be able to run the code below in your GraphQL Playground:

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Master-Key": "MASTER_KEY" // optional
}
# GraphQL
mutation createAGameScore {
  createGameScore(
    input: {
      clientMutationId: "anUniqueId"
      fields: {
        playerName: "Sean Plott",
        score: 1337,
        cheatMode: false
      }
    }
  ) {
    clientMutationId
    gameScore {
      id
      updatedAt
      createdAt
      playerName
      score
      cheatMode
      ACL {
        public {
          write
          read
        }
      }
    }
  }
}
// Response
{
  "data": {
    "createGameScore": {
      "clientMutationId": "anUniqueId",
      "gameScore": {
        "id": "R2FtZVNjb3JlOjZtdGlNcmtXNnY=",
        "updatedAt": "2019-12-02T10:14:28.786Z",
        "createdAt": "2019-12-02T10:14:28.786Z",
        "playerName": "Sean Plott",
        "score": 1337,
        "cheatMode": false,
        "ACL": {
          "public": {
            "write": true,
            "read": true
          }
        }
      }
    }
  }
}

Note: The id is a Relay Global Object Identification, it’s not a Parse objectId. Most of the time the Relay Node Id is a Base64 of the ParseClass and the objectId.

Update

For each class in your application’s schema, Parse Server automatically generates a custom mutation for updating this class’ objects through the GraphQL API.

For example, if you have a class named GameScore in the schema, Parse Server automatically generates a new mutation called updateGameScore.

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Master-Key": "MASTER_KEY" // (optional)
}
# GraphQL
mutation updateAGameScore {
  updateGameScore(
    input: {
      id: "R2FtZVNjb3JlOmM3TVpDZEhQY2w="
      fields: { playerName: "Charles Francois" }
    }
  ) {
    gameScore {
      id
      playerName
    }
  }
}
// Response
{
  "data": {
    "updateGameScore": {
      "gameScore": {
        "id": "R2FtZVNjb3JlOmM3TVpDZEhQY2w=",
        "playerName": "Charles Francois"
      }
    }
  }
}

Note: If you use Apollo Client it’s recommended to request the modified fields and id during the Mutation, then the Apollo Client will automatically update its local store and push the new data across your app; i.e. If you update playerName you should request playerName and id like the code above.

Delete

For each class in your application’s schema, Parse Server automatically generates a custom mutation for deleting this class’ objects through the GraphQL API.

For example, if you have a class named GameScore in the schema, Parse Server automatically generates a new mutation called deleteGameScore.

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Master-Key": "MASTER_KEY" // (optional)
}
mutation deleteAGameScore {
  deleteGameScore(input: { id: "R2FtZVNjb3JlOmM3TVpDZEhQY2w=" }) {
    gameScore {
      id
      playerName
    }
  }
}

The code above should resolve to something similar to this:

// Response
{
  "data": {
    "deleteGameScore": {
      "gameScore": {
        "id": "R2FtZVNjb3JlOmM3TVpDZEhQY2w=",
        "playerName": "Charles Francois"
      }
    }
  }
}

Note: The API returns the deleted object, which can allow you to show messages like “The player Charles François has been successfully removed” on the front end.

Nested Mutation

The GraphQL API supports nested mutations (except for File), so you can create objects with complex relationships in one request. Assuming that we have classes Country, City and Company.

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Master-Key": "MASTER_KEY" // (optional)
}
mutation aNestedMutaiton {
  createCountry(
    input: {
      fields: {
        name: "Mars"
        cities: {
          createAndAdd: [{ name: "Alpha",
            companies: {
              createAndAdd: [{
                name: "Motors"
              }]
            }
          }]
        }
      }
    }
  ) {
    country {
      name
      cities {
        edges {
          node {
            name
            companies {
              edges {
                node {
                  name
                }
              }
            }
          }
        }
      }
    }
  }
}
// Response
{
  "data": {
    "createCountry": {
      "country": {
        "name": "Mars",
        "cities": {
          "edges": [
            {
              "node": {
                "name": "Alpha",
                "companies": {
                  "edges": [
                    {
                      "node": {
                        "name": "Motors"
                      }
                    }
                  ]
                }
              }
            }
          ]
        }
      }
    }
  }
}
Want to contribute to this doc? Edit this section.

Queries

Get

For each class in your application’s schema, Parse Server automatically generates a custom query for getting this class’ objects through the API.

For example, if you have a class named GameScore in the schema, Parse Server automatically generates a new query called gameScore, and you should be able to run the code below in your GraphQL Playground:

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Master-Key": "MASTER_KEY" // (optional)
}
# GraphQL
query getAGameScore {
  gameScore(id: "R2FtZVNjb3JlOjZtdGlNcmtXNnY=") {
    id
    score
    playerName
    score
    cheatMode
    ACL {
      public {
        read
        write
      }
    }
  }
}
// Response
{
  "data": {
    "gameScore": {
      "id": "R2FtZVNjb3JlOjZtdGlNcmtXNnY=",
      "score": 1337,
      "playerName": "Sean Plott",
      "cheatMode": false,
      "ACL": {
        "public": {
          "read": true,
          "write": true
        }
      }
    }
  }
}

Get with Relay

With the Relay specification you also have the choice to use GraphQL Fragments through the node GraphQL Query. For a GameScore object the following query will do the job.

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Master-Key": "MASTER_KEY" // (optional)
}
# GraphQL
query getGameScoreWithNodeRelay {
  node(id: "R2FtZVNjb3JlOjZtdGlNcmtXNnY") {
    id
    __typename
    ... on GameScore {
      playerName
      score
      cheatMode
    }
  }
}
// Response
{
  "data": {
    "node": {
      "id": "R2FtZVNjb3JlOjZtdGlNcmtXNnY=",
      "__typename": "GameScore",
      "playerName": "Sean Plott",
      "score": 1337,
      "cheatMode": false
    }
  }
}

Here using Node Relay is useful for writing generic requests for your front end components. For example, assuming we already have a User with a Relay Node Id: X1VzZXI6Q1lMeWJYMjFjcw== and username: "johndoe".

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Master-Key": "MASTER_KEY" // (optional)
}
# GraphQL
query genericGet {
  node(id: "X1VzZXI6Q1lMeWJYMjFjcw==") {
    id
    __typename
    ... on User {
      id
      username
    }
    ... on GameScore {
      playerName
      score
      cheatMode
    }
  }
}
// Response
{
  "data": {
    "node": {
      "id": "X1VzZXI6Q1lMeWJYMjFjcw==",
      "__typename": "User",
      "username": "johndoe"
    }
  }
}

Find

For each class in your application’s schema, Parse Server automatically generates a custom query for finding this class’ objects through the GraphQL API.

For example, if you have a class named GameScore in the schema, Parse Server automatically generates a new query called gameScores, and you should be able to run the code below in your GraphQL Playground:

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Master-Key": "MASTER_KEY" // (optional)
}
# GraphQL
query getSomeGameScores{
  gameScores {
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    count
    edges {
      cursor
      node {
        id
        playerName
        score
        cheatMode
      }
    }
  }
}
// Response
{
  "data": {
    "gameScores": {
      "pageInfo": {
        "hasNextPage": false,
        "hasPreviousPage": false,
        "startCursor": "YXJyYXljb25uZWN0aW9uOjA=",
        "endCursor": "YXJyYXljb25uZWN0aW9uOjI="
      },
      "count": 3,
      "edges": [
        {
          "cursor": "YXJyYXljb25uZWN0aW9uOjA=",
          "node": {
            "id": "R2FtZVNjb3JlOjZtdGlNcmtXNnY=",
            "playerName": "Sean Plott",
            "score": 1337,
            "cheatMode": false
          }
        },
        {
          "cursor": "YXJyYXljb25uZWN0aW9uOjE=",
          "node": {
            "id": "R2FtZVNjb3JlOnp2cHdTYXlmYnA=",
            "playerName": "John Doe",
            "score": 13,
            "cheatMode": true
          }
        },
        {
          "cursor": "YXJyYXljb25uZWN0aW9uOjI=",
          "node": {
            "id": "R2FtZVNjb3JlOjNmWjBoQVJDVU0=",
            "playerName": "Steve Jordan",
            "score": 134,
            "cheatMode": false
          }
        }
      ]
    }
  }
}

Where

You can use the where argument to add constraints to a class find query. See the example below:

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Master-Key": "MASTER_KEY" // (optional)
}
# GraphQL
query getSomeGameScores {
  gameScores(where: {
  	score: { greaterThan: 158 }
  }) {
    count
    edges {
      cursor
      node {
        id
        playerName
        score
        cheatMode
      }
    }
  }
}
// Response
{
  "data": {
    "gameScores": {
      "count": 1,
      "edges": [
        {
          "cursor": "YXJyYXljb25uZWN0aW9uOjA=",
          "node": {
            "id": "R2FtZVNjb3JlOjZtdGlNcmtXNnY=",
            "playerName": "Sean Plott",
            "score": 1337,
            "cheatMode": false
          }
        }
      ]
    }
  }
}

Visit your GraphQL Playground if you want to know all the available constraints.

Order

You can use the order argument to select in which order the results are returned in a class find query. See the example below:

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Master-Key": "MASTER_KEY" // (optional)
}
# GraphQL
query getSomeGameScores {
  gameScores(
  	where: {
  	  cheatMode: { equalTo: false }
  	},
  	order: score_ASC
  ) {
    count
    edges {
      cursor
      node {
        id
        playerName
        score
        cheatMode
      }
    }
  }
}
// Response
{
  "data": {
    "gameScores": {
      "count": 2,
      "edges": [
        {
          "cursor": "YXJyYXljb25uZWN0aW9uOjA=",
          "node": {
            "id": "R2FtZVNjb3JlOjNmWjBoQVJDVU0=",
            "playerName": "Steve Jordan",
            "score": 134,
            "cheatMode": false
          }
        },
        {
          "cursor": "YXJyYXljb25uZWN0aW9uOjE=",
          "node": {
            "id": "R2FtZVNjb3JlOjZtdGlNcmtXNnY=",
            "playerName": "Sean Plott",
            "score": 1337,
            "cheatMode": false
          }
        }
      ]
    }
  }
}

Pagination

Relay Node Cursor provides a simple way to get efficient and easy to use pagination.

With Relay you can build flexible pagination based on cursors, here is the main effect of each argument:

  • skip: a regular skip to exclude some results
  • first: similar to a limit parameter but starts from the first result, e.g. first: 10 retrieves the first 10 results
  • last: retrieve the last results, e.g. last: 10 retrieves the last 10 results
  • before: get objects before the provided Cursor, in combination with after it allows you to build inverted pagination
  • after: get objects after the provided Cursor, in combination with first you get a classic pagination similar to skip & limit

You can combine multiple parameters like: before & last or after & first, assuming you have an existing cursor.

Note: cursor is different to id, it is a temporary pagination ID for the query.

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Master-Key": "MASTER_KEY" // (optional)
}
# GraphQL
query getSomeGameScores {
  gameScores(after: "YXJyYXljb25uZWN0aW9uOjE") {
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    count
    edges {
      cursor
      node {
        id
        playerName
        score
        cheatMode
      }
    }
  }
}
// Response
{
  "data": {
    "gameScores": {
      "pageInfo": {
        "hasNextPage": false,
        "hasPreviousPage": true,
        "startCursor": "YXJyYXljb25uZWN0aW9uOjI=",
        "endCursor": "YXJyYXljb25uZWN0aW9uOjI="
      },
      "count": 3,
      "edges": [
        {
          "cursor": "YXJyYXljb25uZWN0aW9uOjI=",
          "node": {
            "id": "R2FtZVNjb3JlOjNmWjBoQVJDVU0=",
            "playerName": "Steve Jordan",
            "score": 134,
            "cheatMode": false
          }
        }
      ]
    }
  }
}

Note: count is a global count for available results, it’s not the number of edges returned by the request.

Nested Query

The GraphQL API supports nested queries, so you can find object and then execute query on relational child fields. Assuming that we have classes Country, City, Company:

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Master-Key": "MASTER_KEY" // (optional)
}
query aNestedQuery {
  countries(where: {
    name: { matchesRegex: "Ma", options: "i" }
  }) {
    edges {
      node {
        name
        cities(where: {
          name: { matchesRegex: "pha", options: "i"}
        }) {
          edges {
            node {
              name
            }
          }
        }
      }
    }
  }
}
// Response
{
  "data": {
    "countries": {
      "edges": [
        {
          "node": {
            "name": "Mars",
            "cities": {
              "edges": [
                {
                  "node": {
                    "name": "Alpha"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}

Relational Query

The GraphQL API supports complex parent relational queries. It means that all the Pointer and Relation fields in your database can be used easily throughout the API to query complex relational data. Let’s take a look at the power of this feature.

Parent Relation Style

Assuming that we have a Country class, City class, Street class and House class.

  • Country has a cities Relation field.
  • City has a streets Relation field.
  • Street has a houses Relation field.

Let’s build a query matching countries that contain at least one city with more than 20,000 people and that contain at least one street that matches /rue/i regex and this street should contain at least one house with a name equal to Parse Members.

The GraphQL API can handle this type of complex relational query with ease.

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Master-Key": "MASTER_KEY" // (optional)
}
# GraphQL
{
  countries(
    where: {
      cities: {
        have: {
          peoplesNumber: { greaterThan: 20000 }
          streets: {
            have: {
              name: { matchesRegex: "rue", options: "i" }
              houses: { have: { name: { equalTo: "Parse Members" } } }
            }
          }
        }
      }
    }
  ) {
    edges {
      node {
        name
        cities {
          edges {
            node {
              name
              peoplesNumber
              streets {
                edges {
                  node {
                    name
                    houses {
                      edges {
                        node {
                          name
                        }
                        ... too many brackets here
}
// Response
{
  "data": {
    "countries": {
      "edges": [
        {
          "node": {
            "name": "France",
            "cities": {
              "edges": [
                {
                  "node": {
                    "name": "Toulouse",
                    "peoplesNumber": 400000,
                    "streets": {
                      "edges": [
                        {
                          "node": {
                            "name": "rue jean jaures",
                            "houses": {
                              "edges": [
                                {
                                  "node": {
                                    "name": "Parse Members"
                                  }
                                  ... too many brackets here
}

Child Relation Style

Assuming that we have a Country class, City class, Street class, House class.

  • House has a street Pointer field.
  • Street has a city Pointer field.
  • City has a country Pointer field.

Let’s build a query matching houses where the street has a city that has a country with a name equal to France.

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Master-Key": "MASTER_KEY" // (optional)
}
# GraphQL
{
  houses(
    where: {
      street: {
        have: {
          city: {
            have: {
              country: {
                have: {
                  name: { equalTo: "France" }
                }
              }
            }
          }
        }
      }
    }
  ) {
    edges {
      node {
        name
        street {
          name
          city {
            name
            country {
              name
            }
          }
        }
      }
    }
  }
}

// Response
{
  "data": {
    "houses": {
      "edges": [
        {
          "node": {
            "name": "Parse Members",
            "street": {
              "name": "rue jean jaures",
              "city": {
                "name": "Toulouse",
                "country": {
                  "name": "France"
                }
              }
            }
          }
        }
      ]
    }
  }
}
Want to contribute to this doc? Edit this section.

Users

In general, users have the same features as other objects. The differences are that user objects must have a username and password, the password is automatically encrypted and stored securely, and Parse Server enforces the uniqueness of the username and email fields.

Therefore you can manage users objects using the createUser, user, users, updateUser, and deleteUser operations. Additionally, you can use the signUp, logIn, and logOut operations.

Signing Up

Signing up a new user differs from creating another object in that the username and password fields are required. The password field is handled differently than the others; it is encrypted with bcrypt when stored in the database and never returned to any client request.

You can ask Parse Server to verify user email addresses in your application settings. With this setting enabled, all new user registrations with an email field will generate an email confirmation at that address. You can check whether the user has verified their email with the emailVerified field.

To sign up a new user, use the signUp mutation. For example:

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Master-Key": "MASTER_KEY" // (optional)
}
# GraphQL
mutation signUp {
  signUp(
    input: {
      userFields: {
        username: "johndoe"
        password: "ASuperStrongPassword"
        email: "[email protected]"
      }
    }
  ) {
    viewer {
      sessionToken
      user {
        username
        email
      }
    }
  }
}
// Response
{
  "data": {
    "signUp": {
      "viewer": {
        "sessionToken": "r:a0ec8428409b6b85c6f54ab1e654c53d",
        "user": {
          "username": "johndoe",
          "email": "[email protected]"
        }
      }
    }
  }
}

Note that a field called sessionToken has been returned. This token can be used to authenticate subsequent operations as this user.

Logging In

After you allow users to sign up, you need to let them log in to their account with a username and password in the future. To do this, use the logIn mutation:

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Master-Key": "MASTER_KEY" // optional
}
mutation logIn {
  logIn(input: { username: "johndoe", password: "ASuperStrongPassword" }) {
    viewer {
      sessionToken
      user {
        username
        email
      }
    }
  }
}
// Response
{
  "data": {
    "logIn": {
      "viewer": {
        "sessionToken": "r:b0dfad1eeafa4425d9508f1c0a15c3fa",
        "user": {
          "username": "johndoe",
          "email": "[email protected]"
        }
      }
    }
  }
}

Note that, when the user logs in, Parse Server generates a new sessionToken for future operations.

Using Session Token

For authenticating an operation as a specific user, you need to pass the X-Parse-Session-Token header with its valid session token.

You can easily do this in the GraphQL Playground. There is an option called HTTP HEADERS in its bottom left side. Use this option to replace the default X-Parse-Master-Key header by a valid X-Parse-Session-Token header. You should have something like this:

Session Token Header

After setting up the X-Parse-Session-Token header, any operation will run as this user. For example, you can run the code below to validate the session token and return its associated user:

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Session-Token": "r:b0dfad1eeafa4425d9508f1c0a15c3fa"
}
# GraphQL
query viewer {
  viewer {
    sessionToken
    user {
      username
      email
    }
  }
}
// Response
{
  "data": {
    "viewer": {
      "sessionToken": "r:b0dfad1eeafa4425d9508f1c0a15c3fa",
      "user": {
        "username": "johndoe",
        "email": "[email protected]"
      }
    }
  }
}

Logging Out

You can log out a user through the logOut mutation. You need to send the X-Parse-Session-Token header and run code like the below example:

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Session-Token": "r:b0dfad1eeafa4425d9508f1c0a15c3fa"
}
# GraphQL
mutation logOut {
  logOut(input: { clientMutationId: "logOut" }) {
    clientMutationId
    viewer {
      user {
        username
        email
      }
    }
  }
}

// Response
{
  "data": {
    "logOut": {
      "clientMutationId": "logOut",
      "viewer": {
        "user": {
          "username": "johndoe",
          "email": "[email protected]"
        }
      }
    }
  }
}

Resetting Passwords

To use the resetPassword mutation your Parse Server must have an email adapter configured.

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
}
# GraphQL
mutation resetPassword {
  resetPassword(input: { email: "[email protected]" }) {
    ok
  }
}
// Response
{
  "data": {
    "resetPassword": {
      "ok": true,
    }
  }
}

Send Email Verification

The verification email is automatically sent on sign up; this mutation is useful if the user didn’t receive the first email. Again, an email adapter must be configured for this mutation to work.

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
}
# GraphQL
mutation sendVerificationEmail {
  sendVerificationEmail(input: { email: "[email protected]" }) {
    ok
  }
}

// Response
{
  "data": {
    "sendVerificationEmail": {
      "ok": true,
    }
  }
}
Want to contribute to this doc? Edit this section.

Files

The GraphQL API supports file upload via GraphQL Upload, to send a File through GraphQL it’s recommended to use the Apollo Upload Client.

Add a File field

First of all we will update our GameScore class with a screenshot field of type File.

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Master-Key": "MASTER_KEY"
}
# GraphQL
mutation updateGameScoreClass {
  updateClass(
    input: { 
      name: "GameScore",
      schemaFields: { 
        addFiles: [{ name: "screenshot" }]
      }
    }
  ) {
    class {
      name
    }
  }
}
// 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.

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Master-Key": "MASTER_KEY" // (optional)
}
# 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
    }
  }
}
// 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.

// Header
{
  "X-Parse-Application-Id": "APPLICATION_ID",
  "X-Parse-Master-Key": "MASTER_KEY" // (optional)
}
# 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
      }
    }
  }
}
// Response
{
  "data": {
    "createGameScore": {
      "gameScore": {
        "screenshot": {
          "name": "6a4d43c3f0512bcb6bf05b6b0e7db47d_file.png",
          "url": "http://localhost:1337/graphq/files/APPLICATION_ID/6a4d43c3f0512bcb6bf05b6b0e7db47d_file.png"
        }
      }
    }
  }
}
Want to contribute to this doc? Edit this section.

Customisation

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

Whilst it’s great to simply plug GraphQL into your Parse setup and immediately query any of your existing classes, you may find that this level of exposure is not suitable to your project. We have therefore provided a flexible way to limit which types, queries mutations are exposed within your GraphQL schema.

Configuration Options

By default, no configuration is needed to get GraphQL working with your Parse Server. All of the following settings are completely optional, and can be provided or omitted as desired. To configure your schema, you simply need to provide a valid JSON object with the expected properties as described below:

// The properties with ? are optional

interface ParseGraphQLConfiguration {
  // All classes enabled by default
  // Provide an empty array to disable all classes
  enabledForClasses?: Array<string>;

  // Selectively disable specific classes
  disabledForClasses?: Array<string>;

  // Provide an array of per-class settings
  classConfigs?: Array<{

    // You must provide a className
    // Only provide one config object per class
    className: string;

    type?: {

      // By default, all fields can be sent for
      // a create or update mutation. Use this
      // setting to limit to specific fields.
      inputFields?: {
        create?: Array<string>;
        update?: Array<string>;
      };

      // By default, all fields can be resolved
      // on a get or find query. Use this to limit
      // which fields can be selected.
      outputFields?: Array<string>;

      // By default, all valid fields can be used
      // to filter a query. Use this to limit
      // which fields can be used to constrain a query.
      constraintFields?: Array<string>;

      // By default, all valid fields can be used
      // to sort the results of a query. Use this to
      // limit which fields can be used to sort a query
      // and which direction that sort can be set to.
      sortFields?: {
        field: string;
        asc: boolean;
        desc: boolean;
      }[];
    };

    // By default, a get and find query type is created
    // for all included classes. Use this to disable
    // the available query types for this class.
    query?: {
      get?: boolean;
      find?: boolean;
      getAlias?: String;
      findAlias?: String;
    };

    // By default, all write mutation types are
    // exposed for all included classes. Use this to disable
    // the available mutation types for this class and optionally 
    // override the default generated name with aliases.
    mutation?: {
      create?: boolean;
      update?: boolean;
      destroy?: boolean;
      createAlias?: String,
      updateAlias?: String,
      destroyAlias?: String,
    };
  }>
}

Set or Update Configuration

We have provided a public API in ParseGraphQLServer which accepts the above JSON object for setting (and updating) your Parse GraphQL Configuration, setGraphQLConfig:

  const parseGraphQLServer = new ParseGraphQLServer(parseServer, {
    graphQLPath: parseServerConfig.graphQLPath,
    playgroundPath: parseServerConfig.playgroundPath
  });

  const config = {
    // ... ParseGraphQLConfiguration
  };

  await parseGraphQLServer.setGraphQLConfig(config);       

Include or Exclude Classes

By default, all of your Parse classes, including the defaults such as Parse.User, Parse.Session, Parse.Role are added to the schema. You can restrict this using the enabledForClassess or disabledForClassess options, which accepts an array of class names.

In the following example, we limit our GraphQL schema to only expose the default _User class, along with a few custom classes:

{
  "enabledForClasses": ["_User", "Book", "Review", "Comment"],
  "disabledForClasses": null
}

In the following example, we limit our GraphQL schema by hiding some sensitive classes:

{
  // undefined or null results in the default behaviour, i.e. include all classes
  "enabledForClasses": undefined,
  // override the included classes by filtering out the following:
  "disabledForClasses": [ "UserSensitiveData", "ProductOrder", "Invoice" ]
}

Input Types

By default, we enrich the schema by generating a number of Input Types for each class. This, as a healthy side-effect, improves development experience by providing type-completion and docs, though the true purpose is to define exactly what fields are exposed and useable per operation type. You can provide a type setting for any or each of your classes to limit which fields are exposed:

In the following example, we have a custom class called Review where the fields rating and body are allowed on the create mutation, and the field numberOfLikes on the update mutation:

{
  "classConfigs": [
    {
      "className": "Review",
      "type": {
        "inputFields": {
          "create": ["rating", "body"],
          "update": ["numberOfLikes"]
        }
      }
    }
  ]
}

You may decide to restrict which fields can be resolved when getting or finding records from a given class, for example, if you have a class called Video which includes a sensitive field dmcaFlags, you can hide this field by explicitly stating the fields that can be resolved:

{
  "classConfigs": [
    {
      "className": "Video",
      "type": {
        "outputFields": ["name", "author", "numberOfViews",   "comments", "cdnUrl"]
      }
    }
  ]
}

In production-grade environments where performance optimisation is critical, complete control over query filters and sortability is required to ensure that unindexed queries are not executed. For this reason, we provide a way to limit which fields can be used to constrain a query, and which fields (including the direction) can be used to sort that query.

In the following example, we set the fields name and age as the only two that can be used to filter the _User class, and defining the createdAt and age fields the only sortable field whilst disabling the ascending direction on the createdAt field:

{
  "classConfigs": [
    {
      "className": "_User",
      "type": {
         "constraintFields": ["name", "age"],
          "sortFields": [
            {
              "field": "createdAt",
              "desc": true,
              "asc": false
            },
            {
              "field": "age",
              "desc": true,
              "asc": true
            }
          ]
        }
      }
  ]
}

Queries

By default, the schema exposes a get and find operation for each class, for example, get_User and find_User. You can disable either of these for any class in your schema, like so:

{
  "classConfigs": [
    {
      "className": "_User",
      "query": {
        "get": true,
        "find": false
      }  
    },
    {
      "className": "Review",
      "query": {
        "get": false,
        "find": true
      }  
    }
  ]
}

By default, generated query names use pluralized version of className. You can override this behaviour with getAlias/findAlias. This is useful when your collection is named in plural or when singular/plural forms are same e.g. Data:

{
  "classConfigs": [
    {
      "className": "Likes",
      "query": {
        "getAlias": "like"
      }  
    },
    {
      "className": "Data",
      "query": {
        "findAlias": "findData"
      }  
    }
  ]
}

Mutations

By default, the schema exposes a create, update and delete operation for each class, for example, create_User, update_User and delete_User. You can disable any of these mutations for any class in your schema, like so:

{
  "classConfigs": [
    {
      "className": "_User",
      "mutation": {
        "create": true,
        "update": true,
        "destroy": true
      }  
    },
    {
      "className": "Review",
      "mutation": {
        "create": true,
        "update": false,
        "destroy": true
      }  
    }
  ]
}

Note: the delete mutation setting key is named destroy to avoid issues due to delete being a javascript reserved word.

You can optionally override the default generated mutation names with aliases:

{
  "classConfigs": [
    {
      "className": "Record",
      "mutation": {
        "createAlias": "newRecord",
        "updateAlias": "changeRecord",
        "destroyAlias": "eraseRecord"
      }  
    }
  ]
}
Want to contribute to this doc? Edit this section.

Optimization

Indexing

To optimize your server/database performance and response time you need to configure some indexes based on the types of queries that you use in your app. Currently index manipulations are not supported on the GraphQL API but you can use the Parse JS SDK Indexes API

Here’s a simple example:

# First we update the user class
mutation {
  updateClass(
    input: {
      name: "_User"
      schemaFields: {
        addStrings: [{ name: "firstname" }, { name: "lastname" }]
        addDates: [{ name: "birthdate" }]
        addNumbers: [{ name: "credit" }]
      }
    }
  ) {
    class {
      name
    }
  }
}
# Then lets assume that we have this query in our app
query ASuperUsedQuery {
  users(
    where: {
      firstname: { in: ["John", "Michael", "Sabrina"] }
      lastname: { matchesRegex: "^Do" }
      birthdate: { exists: true }
      credit: { greaterThanOrEqualTo: 100 }
    },
    order: credit_ASC
  ) {
    edges {
      node {
        id
        firstname
      }
    }
  }
}
// Add the index to user class
const addAnIndexToUserClass = () => {
    // Get current class from database
    const UserClass = await (new Parse.Schema('_User')).get();
    UserClass.addIndex('ASuperUsedQueryIndex', {
        firstname: 1,
        lastname: 1,
        birthdate: 1,
        credit: 1
    });
    await UserClass.update()
    console.log('Index for ASuperUsedQuery created')
}

And thats all, your query is optimized and you should have blazing fast responses even with millions of objects.

Warning: Only add indexes for most used queries, an over indexed MongoDB will eat lots of RAM.

Relational

When using the GraphQL API, use the same best practices to construct your database. In the Queries section we saw both parent and child relations.

In the majority of use cases it’s best to reference the parent object inside the child and use a child query style.

# A Good Schema
mutation EfficientSchema {
  City: createClass(
    input: {
      name: "City"
      schemaFields: {
        addStrings: [{ name: "name" }]
        addPointers: [
            {
                name: "country",
                targetClassName: "Country"
            }
        ]
      }
    }
  ) {
    class {
      name
    }
  }
  Country: createClass(
    input: {
        name: "Country",
        schemaFields: {
            addStrings: [{ name: "name" }]
        }
    }
  ) {
    class {
      name
    }
  }
}
# A Bad Schema
mutation NotEfficientSchema {
  City: createClass(
    input: {
        name: "City",
        schemaFields: {
            addStrings: [{ name: "name" }]
        }
    }
  ) {
    class {
      name
    }
  }
  Country: createClass(
    input: {
      name: "Country"
      schemaFields: {
        addStrings: [{ name: "name" }]
        addRelations: [
            {
                name: "cities",
                targetClassName: "City"
            }
        ]
      }
    }
  ) {
    class {
      name
    }
  }
}

GraphQL Clients

If you use a Graphql Client with a cache system like Apollo Client you must add the id field in each of your graphql Queries and Mutations, your client can now update dynamically its local cache based on your graphql operations.

Note: On Mutation it’s recommended to ask to GraphQL to return the modified fields, then your GraphQL Client can update the object in the local cache.

Here a quick example:

# Cache Optimized Mutation
mutation OptimizedMutation {
  updateUser(
    input: {
        id: "xxxx",
        fields: {
            firstname: "John",
            lastname: "Doe"
        }
    }
  ) {
    user {
      id
      firstname
      lastname
    }
  }
}

Want to contribute to this doc? Edit this section.

Learning More

If you look at the right side of your GraphQL Playground, you will see the DOCS and SCHEMA menus. They are automatically generated by analyzing your application schema and contain all operations that you can call for your application, including the automatic class queries and mutations. Please refer to them and learn more about everything that you can do with your Parse GraphQL API.

GraphQL Docs

Additionally, the GraphQL Learn Section is a very good source to start learning about the power of the GraphQL language.

Want to contribute to this doc? Edit this section.