Extensions to GraphQL

The API Gateway extends the GraphQL specification with the following additional schema directives.

@cost
@listSize
@remove

`@cost`

The @cost directive associates weight values with types or fields, to be used when calculating the type cost and field cost, respectively, of a request to the GraphQL API.

Syntax

@cost(weight: value)

Argument	Type	Description
`weight`	float	Specifies the weight to apply to the cost calculation for the targeted type or field.

`@listSize`

The @listSize directive applies slicing arguments to fields.

Syntax

@listSize(slicingArguments: [String], requireOneSlicingArgument: Boolean, assumedSize: value, sizedFields: [String])

Argument	Type	Description
`slicingArguments`	List of strings	A list of arguments that are used by the target server to limit the number of values in a list that is returned by a field. These arguments are applied for each separate retrieval of the field in an API request. The arguments specified must correspond with the implementation or configuration on the target server.
`requireOneSlicingArgument`	Boolean	Whether to validate that incoming queries use only one of the slicing arguments. If set to `true` and none of the defined slicing arguments are present, or if more than one argument is present, an error is generated during validation. The default value is `true`.
`assumedSize`	Integer	The size limit that the target server imposes on fields that return a list of values, for each separate retrieval of the field in an API request. The specified value must correspond with the configuration on the target server to apply rate limiting correctly.
`sizedFields`	List of strings	A field that has an assumed size or slicing arguments can return an object that contains a field with a list of values to be sized. Specify a list of fields to be sized. For example, the GraphQL Cursor Connections Specification specifies a connections pattern for pagination that contains fields with slicing arguments `first` or `last`. These fields return a `connections` object, which contains the sized list in an `edges` field.

Nested slicing arguments

A GraphQL schema can also specify slicing arguments that target nested fields within complex input object types.

Example

Consider the following Filter input object type.

input Filter {
  max: Int
  onlyActiveEntries: Boolean
}

Assuming that the max field of the Filter object references a slicing argument that is a scalar value, nested slicing arguments can be defined, as in the following example.

type Query {
  users(filter: Filter): [User] @listSize(slicingArguments: ["filter.max"])
}

The following query specifies the nested slicing argument. The cost analysis assumes that the field Query.users returns a list of 10 users.

querynestedSlicing {
  users(filter: {max: 10}) {
    name
  }
}

Specifying default values for slicing arguments

Default values can be defined for both scalar and complex input types. If no other value is explicitly defined in a query, the cost analysis uses default values.

Note that if a slicing argument has a default value defined and the requireOneSlicingArgument is set to true, queries are allowed to omit that slicing argument.

Example

Consider the following Filter input object type.

input Filter {
  max: Int
  onlyActiveEntries: Boolean
}

The argument Query.users.max and the input field filter.max both specify default values of 10.

type Query {
  users(max: Int = 10): [User]
  filteredUsers(filter: Filter = {max: 10}): [User]
}

`@remove`

The @remove directive specifies conditions for removing types and fields from validation or introspection for each transaction based on values in the API context.

Syntax

@remove(if: [String]) on SCALAR | OBJECT | FIELD_DEFINITION | ARGUMENT_DEFINITION | INTERFACE | UNION | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION

Argument	Type	Description
`if`	List of strings	JSONata condition that specifies the criteria for removal of a type or field from validation or introspection.

Limitations and propagation rules

For limitations and propagation rules, see Limitations and propagation rules for the GraphQL @remove directive.

Example 1

Remove the creditCard type if the current API plan is bronze.

type creditCard @remove(if: ["plan.name in [\"bronze\"]"])

Example 2

Remove the creditCard type if the current API plan is not gold, and remove the field card1 if the API plan is bronze.

type creditCard @remove(if: ["$not(plan.name = \"gold\")"]){
   field1: String
 }
 type User {
   card1: creditCard @remove(if: ["plan.name = 'bronze'", "$not(plan.name = \gold\")"])
 }