Using the GraphQL schema editor

The GraphQL schema editor allows you to a configure a range of settings that are used to calculate the complexity of a GraphQL request, and an associated cost that counts towards the rate limit.

Introduction

When the GraphQL schema editor opens, all the types defined in the GraphQL schema are listed. You can expand a type to display all the fields that are defined for that type.

For each type, you can specify the following setting:

Type weight

The weighting factor that you want to apply to the type for use when calculating the type cost for a request to the GraphQL API. In general, the weighting factor for a type will reflect the resource implications for a request that retrieves values of that type; for example:

A complex object might be weighted more heavily than a String.
Values of one type might be retrieved from a different backend database to values of another type, and accessing one database requires more CPU resource, so types associated with this database are weighted more heavily.

For each field, you can specify the following settings:

Field weight: The weighting factor that you want to apply to the field for use when calculating the field cost of a request to the GraphQL API.
Assumed size: The size limit that the backend server imposes on the number of values of this field that are returned, in a list, for each separate retrieval of the field in an API request. If an assumed size has been defined for this field in the imported GraphQL schema, its value is displayed. You an enter a value, or change the current value, and the schema definition stored in API Connect is updated accordingly. You must ensure that the specified value corresponds with the implementation or configuration on the backend server so that API Connect can apply rate limiting correctly. The assumed size is intended to be configured for fields that return lists of values, to tell the cost analysis how many values to expect.
Slicing arguments: A comma separated list of the arguments that are used by the backend server to limit the number of values of this field that are returned, in a list, for each separate retrieval of the field in an API request. These must correspond with the implementation or configuration on the backend server. For example, there might be slicing arguments of first and last that are used to specify a range of objects to be returned by an API request.
Sized fields: In some cases, a field with a configured Assumed size or Slicing arguments setting returns an object, a field of which returns the values whose number is to be sized. This is common in the connections pattern for pagination, where fields with slicing arguments first or last return a connections object, that contains the sized list in an edges field. The Sized fields option allows the cost analysis to consider these indirect relationships between assumed sizes or slicing arguments and the sized list of values. Supply a comma separated list of field names.

You access the GraphQL schema editor in either of the following ways:

Immediately after creating a new GraphQL proxy API , by clicking Edit API, then clicking the GraphQL Schema tab. For GraphQL proxy API creation details, see Creating a GraphQL proxy API.
By modifying the configuration of an existing API; complete the following steps:
1. In the navigation pane, click Develop, then select the APIs tab.
2. Alongside the GraphQL API definition that you want to work with, click the options icon and then click Edit API.
3. Click the GraphQL Schema tab.

Modifying a setting for a single type or field

For a numerical setting, click the setting alongside the required type or field, then enter the required value, or use the stepper control. For a setting that has a textual value, enter the value directly. You might first want to filter the display to show only a relevant subset of types and fields; see Filtering the display.

Modifying settings for multiple types and fields

To modify settings for multiple types and fields in a single operation, complete the following steps:

Select the check boxes alongside the types and fields whose settings you want to modify.
Click Apply analysis configuration.
On the Type tab, specify the settings that you want to apply to the selected types.
On the Field tab, specify the settings that you want to apply to the selected fields.
Click Apply to apply the settings to the selected types and fields.
When you have made all the required modifications to the selected types and fields, click Done; this actions clears all check box settings.

To to restore any type or field settings to the initial default settings after having applied an analysis configuration, select the check boxes alongside the required types and fields, then click Remove analysis configuration.

You might first want to filter the display to show only a relevant subset of types and fields; see Filtering the display.

Filtering the display

To display only those type and fields that contain a specified string, enter the required filter string in the Search schema field, then press Enter.

If a type matches the filter, the type and all its fields are displayed. If a field matches the filter but not its parent type, the parent type is displayed together with all matching fields. You can enter multiple filter strings; the items displayed are those that contain all strings.

You can now use the operations described in Modifying a setting for a single type or field and Modifying settings for multiple types and fields to update the settings for the displayed types and fields.

To remove a specific filter string from the search, click the Close icon icon for clearing a GraphQL search filter for that filter string. To restore the full type and field display by removing all filter strings, click the Clear icon icon for clearing all GraphQL search filters at the end of the search field.

GraphQL schema warnings

Where applicable, API Connect will recommend updates to the analysis configuration to protect the backend server from excessive resource utilization, and to ensure correct cost estimation for requests. These recommendations are displayed as warnings in the GraphQL schema editor.

If a type contains one or more fields with warnings, this is indicated by a warning count icon GraphQL warning count icon

alongside the type. You can click the warning count icon to see the warnings for that type; the Warnings window opens at the relevant warnings, for example:

To see the fields that have warnings, expand the type; a warning icon GraphQL warning icon is displayed alongside fields with warnings. To see the details of a warning for a field, click the warning icon alongside the field

If you click Accept under any warning in the Warnings window, the recommended update is applied to the schema automatically.

To apply the suggested updates for all warnings in a single operation, click Apply all in the Warnings window, then click Apply to confirm.

You can filter the display to include only items with warnings; click the Menu icon GraphQL menu icon , then select Show warnings only.

Applying @remove directives to types and fields in the GraphQL schema

The @remove GraphQL schema directive specifies conditions for removing items from validation or introspection for each transaction based on values in the API context. For example, you can prevent specific Plans from using certain types or fields.

For more details on the @remove directive, including examples, see rapic_graphql_extensions.html#reference_wrt_bk1_5mb__at_remove.

To apply an @remove directive to an item in your GraphQL schema, complete the following steps:

Click the settings icon in the Show/hide column alongside the required item. The Show/hide settings window opens.
To remove the item depending on a boolean condition, enter the boolean expression in the Custom expression field; the following directive will be added to the item in the schema:
```
@remove(if: [expression])
```
To remove the item unconditionally, change the Show in schema slider control to Hide in schema; the following directive will be added to the item in the schema:
```
@remove(if: ["true"])
```
Click Next. A summary window opens. If the removal is permitted, any related items that will also have the @remove directive applied are listed; for example, if you apply an @remove directive to a type, and that type is referenced as the data type of a field on another type, the @remove directive is also applied to that field. If the removal is not permitted, an explanation is displayed.
If the removal is permitted, click Done to apply the @remove directive. If the removal is not permitted, either click Cancel to close the window or click Back and amend your settings.
To see the updates to the GraphQL JSON schema, click View source.

You can use the settings icon GraphQL settings icon to modify or delete previously applied @remove directives. To remove a conditional @remove directive, delete the expression from the Custom expression field. To remove an unconditional @remove directive, change the Hide in schema slider control to Show in schema.

Viewing the GraphQL schema

To view the GraphQL JSON schema that was previously uploaded, click View source. Note that the schema includes directive statements and attribute values, added by API Connect, that reflect the configuration settings.

Replacing the GraphQL schema

To replace the GraphQL schema, complete the following steps:

Click Replace.
Specify the replacement schema:
- To replace the schema by introspecting a URL, complete the following steps:
  1. Select Introspect from URL.
  2. Enter the URL in the GraphQL server URL field, then click Introspect.
  Note: If you replace the schema from a URL that is different to the one specified as the backend GraphQL server, in the GraphQL server URL field, when the GraphQL proxy API was created, the schema itself is replaced but the backend URL remains unchanged. You must correspondingly modify the URL setting on the invoke policy in the API assembly of your GraphQL proxy API.
- To replace the schema by uploading a file, complete the following steps:
  1. Select Upload schema definition language (SDL) file.
  2. Either drag and drop the file or click the link to select the file from your local file system.
  Note:
  - The schema must be written in the GraphQL Schema Definition Language (SDL). For more information, see Type language in the GraphQL documentation at https://graphql.org/.
  - If you upload a schema from a local file having previously uploaded a schema from a URL, the schema URL setting that is stored in the OpenAPI source for the API, and subsequently displayed in the user interface, retains the previously specified URL value rather than indicating a file location.
All the changes between the replacement schema and the current schema are listed.
Update the schema as required:
- To have all new types and fields shown by default, select New schema for the Update schema defaults giving preference to setting. You can then choose to hide specific items by selecting Hide in the Action column alongside an item. Hiding an item causes an @remove directive to be added to the item in the schema source, as detailed in Applying @remove directives to types and fields in the GraphQL schema.
- To have all new types and fields hidden by default, select Old schema for the Update schema defaults giving preference to setting. You can then choose to show specific items by selecting Show in the Action column alongside an item.
Note: If the current schema contains items that are not in the replacement schema, these items are deleted. Such deletions are shown in the change listing with the Accept setting displayed in the Action column; you cannot change this setting.
Click Next. A change summary page is displayed. If any removals are not permitted, an explanation is displayed, and you cannot complete the schema replacement; either click Cancel to close the window or click Back and amend your settings..
Click Submit to complete the schema replacement.

Downloading the GraphQL schema

To download the GraphQL schema to a local file, click the Download. Note that the downloaded schema includes all additional settings that reflect your configuration updates.