GraphQL: Augmented GraphQL Schema (SDL)

[Moumouls]

Introduce Augmented GraphQL Schema (SDL)

In response of #5894

I would like to propose and discuss the introduction of an SDL system. The main objective will be to help developers improve their GraphQL Server Parse and enable many more features in the future without modifying the Parse Server Core.

Augmented TypeDef file: schema.graphql

const parseGraphQLServer = new ParseGraphQLServer(
  parseServer,
  {
    typeDefs: './schema.graphql'
    graphQLPath: '/graphql',
    playgroundPath: '/playground'
  }
);

@auto: Describe a current Parse class and add auto generation

All other fields will be auto generated

schema.graphql

type Job @auto {
   # Tell to GraphQL that the countries array is a an array of countries
   countries: [Countries]
}

@disableMutations: Disable all mutation or some mutations on the type

schema.graphql

type Job @auto @disableMutations {
   countries: [Countries]
}

OR

type Job @auto @disableMutations(update, delete) {
   countries: [Countries]
}

@disableQueries: Disable all queries or some queries on the type

schema.graphql

type Job @auto @disableQueries {
   countries: [Countries]
}

OR

type Job @auto @disableQueries(get) {
   countries: [Countries]
}

@private: Do not expose a type or a field (in query and input)

schema.graphql

type Job @private

type Job @auto {
   # Tell to GraphQL that the countries array is a an array of countries
   countries: [Countries]
   secretData: String @private
}

@lock: Create/update a Parse.Schema and lock the Class schema

We will create/update the appropriate Parse.Schema. A new way to use Parse.Schema

type Job @lock {
   name: String
   countries: [Countries]
}

@mock: Allow to generate fake datas in dev mode

const parseGraphQLServer = new ParseGraphQLServer(
  parseServer,
  {
    mock: true,
    typeDefs: './schema.graphql'
    graphQLPath: '/graphql',
    playgroundPath: '/playground'
  }
);

type Job @lock {
   name: String @mock(["Developer", "FullStack", "Driver"])
   countries: [Country]
}

type Country @lock {
   name: String @mock(["Developer", "FullStack", "Driver"])
   surface: String @mock(["34 000 000km2"])
}

Allow developers to add description on generated fields

type Job @lock {
  # Here it's a comment displayed on the GraphQL Doc
   name: String
  # Here it's another comment
   countries: [Country]
}

Provide a Mutation loadSchema that allow to send this schema to the server

Need Master Key

type Mutation {
    loadSchema(schema: String): Boolean
}

What do you think about this @davimacedo ?

[davimacedo]

We already have similar functionalities (but they are not in the docs yet). Have you seen these PRs?
#5782
#5821
#5836
#5828

My worry with this project is that it's going to get lost pretty quickly due to a lack of balance between documentation and improvement. I think we should create some balance before things go out of hand.

[davimacedo]

@GoGross I also have this concern. Communicating the features really well through the docs is as important as creating new features. I had actually started building the docs for these PRs but, because of the recent GraphQL discussions around changing the current API, I left it on hold until we have done the breaking changes we expect. But any help here is really appreciated and I think we could accelerate the missing docs. Would be willed to help us on this?

[Moumouls]

I think that PRs concerning the configuration of the Parse GraphQL Server should only be validated with a linked PR Doc to avoid a implementation mismatch 🚀

[davimacedo]

Yes. That's also a good idea. Let's do this for the next PRs.