Apollo Connectors Preview Features

Try out the latest features of Apollo Connectors

Want to try out the latest and greatest features of Apollo Connectors? You're in the right place!

Before you jump in, there are a couple important pieces of information:

  • All of these features are subject to change. Use care when updating composition or GraphOS Router.

  • Tell us what you think before these features are stable.

Enable Preview Features

  1. Use GraphOS Router v2.8.0-preview.0 or greater. When running rover dev locally, set this environment variable:

    Bash
    1APOLLO_ROVER_DEV_ROUTER_VERSION=2.8.0-preview.0

  2. Configure the router to enable the preview version of Connectors (in whatever file you pass for --router-config, typically router.yaml):

    YAML
    1connectors:
2  preview_connect_v0_3: true

  3. Use composition v2.12.0-preview.8 or greater with rover and the Federation Next build pipeline in Studio. When running rover locally, this version can be configured in a YAML file specified with --supergraph-config:

    YAML
    1federation_version: =2.12.0-preview.8

  4. Update your schemas to use the preview version of Connectors:

    GraphQL
    1extend schema
2 @link(
3   url: "https://specs.apollo.dev/connect/v0.3",
4   import: ["@source", "@connect"]
5 )

The order of these steps is important. Older versions of the router don't accept the configuration setting, and routers without the configuration reject schemas composed with the latest composition version.

The $env variable

The $env variable is a new feature for accessing environment variables in your Connectors. This is useful for API keys or other configuration values that you don't want to hard-code into your schema.

New methods and operators

Array methods

MethodDescription
findReturns the first item in the array that matches the criteria outlined in the first argument of find.
filterReturns a new array containing all array items that match the criteria outlined in the first argument of filter.
getFor a string, returns the character at the specified index. For an array, returns the item at the specified index. For an object, returns the property with the specified name.

Logical operators

MethodDescription
neReturns true if the value is not equal to the argument.
inReturns true if the list of arguments contains the value.
containsReturns true if the array contains the argument value.
lteReturns true if the value is less than or equal to the argument value.
gtReturns true if the value is greater than the argument value.
ltReturns true if the value is less than the argument value.
gteReturns true if the value is greater than or equal to the argument value.
orReturns true if the value or any of the arguments are true.
notInverts the boolean of the value. true becomes false, and false becomes true.
eqReturns true if the value is equal to the argument.
andGiven two or more values to compare, returns true if all of the values are true.

Math methods

MethodDescription
modDivides the value by the argument and returns the remainder.
subSubtracts the argument from the value.
addAdds the value and the argument.
divDivides the value by the argument.
mulMultiplies the value by the argument.

Type coercion

MethodDescription
parseIntConverts a value to an Int.
toStringConverts an input to a String.

The ?? and ?! coalescing operators

The new ?? and ?! nullish- and None-coalescing operators enable providing reliable default expressions when an expression to the left of the ?? or ?! evaluates to null or None (as the ?? operator does) or only None (as the ?! operator does):

Connector Mapping Language
1people: $(people ?? [])
2bOrDefault: $(b ?? "default")
3default: $(null ?? "default")
4alsoDefault: $(missing ?? "default")
5multiple: $(this ?? that ?? null)
6true: $(true ?? "default")
7safeSlice: array->slice($args.sliceStart ?? 0, $args.sliceEnd ?? 10)
8nullAllowed: $(null ?! "default")
9stillDefault: $(missing ?! "default")

See the section on defaulting values for more information on these operators.

isSuccess for handling non-20x responses

By default, Apollo Connectors map successful 20X HTTP responses to the data property of the GraphQL response, and map other status codes to the errors property. The isSuccess argument for both @source and @connect directives enables you to customize this behavior.

The isSuccess expression uses the Connectors mapping language and must evaluate to a boolean. If the result is true, the router applies the selection mapping to the response and merges the result to the data property. If it's false, the router applies the errors.message and errors.extensions mappings and appends the result to the errors property.

You can use expressions like isSuccess: "$status->match([200, true], [400, true], [@, false])" to map the response to data for specific status codes.

Here is an example that will never result in a GraphQL error by setting isSuccess to true:

GraphQL
type Mutation {
  createProduct: CreateProductResponse!
    @connect(
      http: { GET: "https://api.dev/endpoint-that-can-fail" }
      isSuccess: "$(true)"
      selection: """
      product { id }
      errors { message }
      """
    )
}

type CreateProductResponse {
  product: Product
  errors: [Error]
}

Learn more about error handling with Connectors.
Feedback

Edit in VSCode

Ask Community