Apollo Connectors Changelog

Connectors 0.3 & Federation 2.12.0

Upgrade instructions

1. Upgrade local development environments for testing:

   • supergraph.yaml files should have federation_version set to =2.12.0 or later.

   • Rover should be v0.36.0 or later.

2. Update your deployed routers to support Connectors 0.3.

3. Update the Build pipeline in GraphOS Studio to v2.12.

   • Go to your graph's Settings page and click Update version to update your Federation version to 2.12.

4. Update your schemas to use Connectors v0.3:

   GraphQL

   copy

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

Learn more about Connectors version requirements.

New features

Environment variable access with $env

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

New array methods

Added new array manipulation methods:

• find - Returns the first item in an array that matches the specified criteria

• filter - Returns a new array containing all items that match the specified criteria

• get - Returns the character at a specified index (for strings), item at a specified index (for arrays), or property with a specified name (for objects)

New logical operators

Added logical operators for conditional expressions:

• ne - Not equal to

• in - Value is in the list of arguments

• contains - Array contains the argument value

• lte - Less than or equal to

• gt - Greater than

• lt - Less than

• gte - Greater than or equal to

• or - Logical OR

• not - Inverts boolean value

• eq - Equal to

• and - Logical AND

New math methods

Added mathematical operations:

• mod - Modulo operation (remainder after division)

• sub - Subtraction

• add - Addition

• div - Division

• mul - Multiplication

Type coercion methods

Added methods for type conversion:

• parseInt - Converts a value to an Int

• toString - Converts a value to a String

Nullish coalescing operators

The new ?? and ?! operators enable providing default values when expressions evaluate to null or None:

• ?? - Coalesces on null or None

• ?! - Coalesces only on None

1people: $(people ?? [])
2bOrDefault: $(b ?? "default")
3nullAllowed: $(null ?! "default")
4safeSlice: array->slice($args.sliceStart ?? 0, $args.sliceEnd ?? 10)

Custom success handling with isSuccess

The new isSuccess argument for @source and @connect directives enables customizing how HTTP status codes are handled. By default, 20X responses map to data and other status codes map to errors. With isSuccess, you can customize this behavior using expressions that evaluate to a boolean.

1type Mutation {
2  createProduct: CreateProductResponse!
3    @connect(
4      http: { GET: "https://api.dev/endpoint-that-can-fail" }
5      isSuccess: "$(true)"
6      selection: """
7      product { id }
8      errors { message }
9      """
10    )
11}

Router 2.3.0 & Composition 2.11.0

Upgrade instructions

1. Upgrade local development environments for testing:

   • supergraph.yaml files should have federation_version set to =2.11.0 or later.

   • Rover should be v0.30.0 or later.

2. Update your deployed routers to v2.3.0.

3. Update the Build pipeline in GraphOS Studio to v2.11.

   • Go to your graph's Settings page and click Update version to update your Federation version to 2.11.

Learn more about Connectors version requirements.

New features

Resolve entities using Connectors on types

You can now add @connect directly on types instead of adding a Query or Mutation field.

type Price @key(fields: "id") {
  id: ID!
  active: Boolean
  currency: String
  unitAmount: Float
}

type Query {
  price(id: ID!): Price 
    @connect(
      source: "ecomm"
      http: { GET: "/prices/{$args.id}"}
      selection: """
        id
        active
        currency
        unitAmount: unit_amount
      """
      entity: true
    )
    @inaccessible
}

type Price @key(fields: "id")
  @connect(
    source: "ecomm"
    http: { GET: "/products/{$this.id}/price" }
    selection: """
      id
      active
      currency
      unitAmount
    }
    """
  ){
  id: ID!
  active: Boolean
  currency: String
  unitAmount: Float
}

This eliminates the need to include entity: true when resolving entities. See Where to use @connect for details on when to use @connect on types and fields.

Batch requests with $batch

The new $batch variable allows you to address the N+1 problem by batching requests to REST batch endpoints. This helps optimize your API calls by reducing the number of network requests. Learn more in the batch request documentation.

joinNotNull method

The new ->joinNotNull method allows you to join a list of strings with a comma or other separators. It ignores any null values in the list.

1type Query {
2  products(filterName: String, filterValue: [String]): [Product]
3    @connect(
4      source: "myApi"
5      http: {
6        GET: "/products?{$args.filterName}={$args.filterValue->joinNotNull(',')}"
7      }
8      selection: "id name reviews { id }"
9    )
10}

This is particularly useful for passing lists of IDs to a REST endpoint for batch requests.

1type Review
2  @connect(
3    source: "myApi"
4    http: { GET: "/reviews?ids={$batch.id->joinNotNull(',')}" }
5    selection: "id text rating"
6  ) {
7  id: ID!
8  text: String!
9  rating: Int!
10}

Advanced request URL building

Building URLs is now more flexible with two new options:

• The http.queryParams argument supports repeating and nullable query parameters

• The http.path argument enables building dynamic URL path segments with arrays of values as described in the dynamic path segments documentation.

Request and response header access

New variables $request.headers and $response.headers are now available to access request and response headers when building request URLs, bodies, and in selection mapping. This enables more sophisticated data transformation based on header values. See the variables reference for usage details.

Non-JSON response support

Connectors now supports mapping against endpoints that return non-JSON content types, opening up text-based responses, empty responses, and more. See the response handling documentation for details.

Customized error handling

Customize the message and extensions of the GraphQL response when an HTTP endpoint returns a non-200 status. This gives you greater control over error presentation to clients. Learn more in the error handling documentation.

Router 2.2.0

New features

YAML-based header propagation

Connectors now support the router's header propagation features. See the Connectors traffic shaping documentation for configuration examples.

Router 2.1.2 & Composition 2.10.2

Bug fixes

• Fixed a bug that dropped @context/@fromContext directives from the supergraph schema when any subgraph schema uses Connectors. The context pattern is still available only for subgraph schemas that don't use Connectors.

• Fixed a bug relating to how Connectors methods work. The fix standardizes ->method behavior to apply to the full value of an expression, not each item, when the preceding expression returns an array. For example, prior to this change, the expression $.id->jsonStringify resulted in ["1","2","3"], with each item individually stringified. After the fix, the result is '["1","2","3"]', with the entire array stringified.

Router 2.1.0

New features

Traffic shaping support

Connectors now support the router's traffic shaping features. See the Connectors traffic shaping documentation for configuration examples.

TLS support

Connectors now support the router's TLS features to authenticate and encrypt communications. See the Connectors traffic shaping documentation for configuration examples.

2025-02-18

Router 2.0.0 & Composition 2.10.0

New features

General availability of Apollo Connectors

Apollo Connectors is now generally available.

Migrating from Apollo Connectors preview releases

You must migrate your router Connectors configuration to the GA format once you update your router to v2.0.0. When you update to v2.0.0, configurations from preview releases no longer work.

The key changes between preview and GA versions:

• The top-level preview-connectors configuration has been renamed to connectors.

• Configuration that was previously under subgraphs has now moved to sources.

• Each Connector source is now configured under an entry combining the subgraph name and source name, separated by a .—for example, subgraph_name.source_name.

• Any $config variables should now be placed under their corresponding source configuration.

For example, given the following preview configuration:

1preview_connectors:
2   # This applies globally to all Connectors
3  max_requests_per_operation_per_source: 100
4  subgraphs:
5    example: # The name of the subgraph
6      $config:
7        my.config.value: true # Applies to all sources in this subgraph
8      sources:
9        v1: # Refers to @source(name: "v1")
10          # These configurations apply to Connectors with the "endpoint1" source in the "subgraph1" subgraph
11          override_url: 'https://localhost:5000'
12          max_requests_per_operation: 50
13        v2: # Refers to @source(name: "v2")
14          #  These configurations apply to Connectors with the "endpoint2" source in the "subgraph1" subgraph
15          max_requests_per_operation: 100

The GA configuration would look like this:

1connectors:
2   # This applies globally to all Connectors
3  max_requests_per_operation_per_source: 100
4  sources:
5    subgraph1.endpoint1: # subgraph.source
6      # These configurations apply to Connectors with the "endpoint1" source in the "subgraph1" subgraph
7      override_url: 'https://localhost:5000'
8      max_requests_per_operation: 50
9      $config:
10        my.config.value: true # Applies to the "v1" source
11    subgraph1.endpoint2: # subgraph.source
12      # These configurations apply to Connectors with the "endpoint2" source in the "subgraph1" subgraph
13      max_requests_per_operation: 25
14      another.config.value: true # Applies to the "v2" source

Deprecated preview releases