From d53a189659dae97a640f91df62ce71c50a83f955 Mon Sep 17 00:00:00 2001 From: Omair Vaiyani Date: Mon, 29 Jul 2019 12:57:08 +0100 Subject: [PATCH 1/2] add guide for graphql configuration --- _includes/graphql/customisation.md | 244 +++++++++++++++++++++++++++++ 1 file changed, 244 insertions(+) create mode 100644 _includes/graphql/customisation.md diff --git a/_includes/graphql/customisation.md b/_includes/graphql/customisation.md new file mode 100644 index 000000000..a31071c17 --- /dev/null +++ b/_includes/graphql/customisation.md @@ -0,0 +1,244 @@ +# 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. + +## 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: + +```typescript +// The properties with ? are optional + +interface ParseGraphQLConfiguration { + // All classes enabled by default + // Provide an empty array to disable all classes + enabledForClasses?: Array; + + // Selectively disable specific classes + disabledForClasses?: Array; + + // 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; + update?: Array; + }; + + // By default, all fields can be resolved + // on a get or find query. Use this to limit + // which fields can be selected. + outputFields?: Array; + + // 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; + + // 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; + }; + + // By default, all write mutation types are + // exposed for all included classes. Use this to disable + // the available mutation types for this class. + mutation?: { + create?: boolean; + update?: boolean; + destroy?: boolean; + }; + }> +} +``` + +### 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```: + +```typescript + 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: + +```javascript +{ + enabledForClasses: ["_User", "Book", "Review", "Comment"], + disabledForClasses: null +} +``` + +In the following example, we limit our GraphQL schema by hiding some sensitive classes: + +```javascript +{ + // 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](https://graphql.org/learn/schema/#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: + +```json +{ + 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: + +```json +{ + 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: + +```json +{ + classConfigs: [ + { + className: "_User", + constraintFields: ["name", "age"], + type: { + 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: + + +```json +{ + classConfigs: [ + { + className: "_User", + query: { + get: true, + find: false + } + }, + { + className: "Review", + query: { + get: false, + find: true + } + } + ] +} +``` + +### 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: + + +```json +{ + 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. From dd452a9466fd74af6d8d0c19001f2811d9d72b34 Mon Sep 17 00:00:00 2001 From: Omair Vaiyani Date: Tue, 30 Jul 2019 09:22:59 +0100 Subject: [PATCH 2/2] add new docs to graphql sections and minor fixes --- _includes/graphql/customisation.md | 123 +++++++++++++++-------------- graphql.md | 1 + 2 files changed, 63 insertions(+), 61 deletions(-) diff --git a/_includes/graphql/customisation.md b/_includes/graphql/customisation.md index a31071c17..086c56b0f 100644 --- a/_includes/graphql/customisation.md +++ b/_includes/graphql/customisation.md @@ -81,9 +81,9 @@ interface ParseGraphQLConfiguration { ### 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```: +We have provided a public API in `ParseGraphQLServer` which accepts the above JSON object for setting (and updating) your Parse GraphQL Configuration, `setGraphQLConfig`: -```typescript +```javascript const parseGraphQLServer = new ParseGraphQLServer(parseServer, { graphQLPath: parseServerConfig.graphQLPath, playgroundPath: parseServerConfig.playgroundPath @@ -98,14 +98,15 @@ We have provided a public API in ```ParseGraphQLServer``` which accepts the abov ### 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. +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: + +In the following example, we limit our GraphQL schema to only expose the default `_User` class, along with a few custom classes: ```javascript { - enabledForClasses: ["_User", "Book", "Review", "Comment"], - disabledForClasses: null + "enabledForClasses": ["_User", "Book", "Review", "Comment"], + "disabledForClasses": null } ``` @@ -114,27 +115,27 @@ In the following example, we limit our GraphQL schema by hiding some sensitive c ```javascript { // undefined or null results in the default behaviour, i.e. include all classes - enabledForClasses: undefined, + "enabledForClasses": undefined, // override the included classes by filtering out the following: - disabledForClasses: [ "UserSensitiveData", "ProductOrder", "Invoice" ] + "disabledForClasses": [ "UserSensitiveData", "ProductOrder", "Invoice" ] } ``` ### Input Types -By default, we enrich the schema by generating a number of [Input Types](https://graphql.org/learn/schema/#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: +By default, we enrich the schema by generating a number of [Input Types](https://graphql.org/learn/schema/#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: +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: -```json +```javascript { - classConfigs: [ + "classConfigs": [ { - className: "Review", - type: { - inputFields: { - create: ["rating", "body"], - update: ["numberOfLikes"] + "className": "Review", + "type": { + "inputFields": { + "create": ["rating", "body"], + "update": ["numberOfLikes"] } } } @@ -142,15 +143,15 @@ In the following example, we have a custom class called ```Review``` where the f } ``` -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: +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: -```json +```javascript { - classConfigs: [ + "classConfigs": [ { - className: "Video", - type: { - outputFields: ["name", "author", "numberOfViews", "comments", "cdnUrl"] + "className": "Video", + "type": { + "outputFields": ["name", "author", "numberOfViews", "comments", "cdnUrl"] } } ] @@ -160,25 +161,25 @@ You may decide to restrict which fields can be resolved when getting or finding 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: +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: -```json +```javascript { - classConfigs: [ + "classConfigs": [ { - className: "_User", - constraintFields: ["name", "age"], - type: { - sortFields: [ + "className": "_User", + "type": { + "constraintFields": ["name", "age"], + "sortFields": [ { - field: "createdAt", - desc: true, - asc: false + "field": "createdAt", + "desc": true, + "asc": false }, { - field: "age", - desc: true, - asc: true + "field": "age", + "desc": true, + "asc": true } ] } @@ -189,24 +190,24 @@ In the following example, we set the fields ```name``` and ```age``` as the only ### 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: +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: -```json +```javascript { - classConfigs: [ + "classConfigs": [ { - className: "_User", - query: { - get: true, - find: false + "className": "_User", + "query": { + "get": true, + "find": false } }, { - className: "Review", - query: { - get: false, - find: true + "className": "Review", + "query": { + "get": false, + "find": true } } ] @@ -215,30 +216,30 @@ By default, the schema exposes a ```get``` and ```find``` operation for each cla ### 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: +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: -```json +```javascript { - classConfigs: [ + "classConfigs": [ { - className: "_User", - mutation: { - create: true, - update: true, - destroy: true + "className": "_User", + "mutation": { + "create": true, + "update": true, + "destroy": true } }, { - className: "Review", - mutation: { - create: true, - update: false, - 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. +**Note**: the `delete` mutation setting key is named `destroy` to avoid issues due to `delete` being a javascript reserved word. diff --git a/graphql.md b/graphql.md index 087c7d217..365d14a7e 100644 --- a/graphql.md +++ b/graphql.md @@ -14,6 +14,7 @@ sections: - "graphql/your-first-query.md" - "graphql/objects.md" - "graphql/users.md" +- "graphql/customisation.md" - "graphql/learning-more.md" ---