Extensions to GraphQL

The API Connect DataPower® API Gateway extends the GraphQL specification by providing additional schema directives.

@cost

The @cost directive is used to associate 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)
Arguments
Argument name Type Description
weight float Specifies the weight to apply to the field cost calculation when a resolve function for the targeted type is addressed by the query.

@listSize

The @listSize directive applies slicing arguments to fields.

Syntax
@listSize(slicingArguments: [String], requireOneSlicingArgument: Boolean, assumedSize: value, sizedFields: [String])
Arguments
Argument name Type Description
slicingArguments List of strings A list of arguments that are used by the backend 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 backend 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 backend 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 backend 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.

For 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.

For 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 GraphQL schema directive specifies conditions for removing types and fields 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.

Syntax
@remove(if: [String]) on SCALAR | OBJECT | FIELD_DEFINITION | ARGUMENT_DEFINITION | INTERFACE | UNION | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION
Arguments
Argument name 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\")"])
}