Apollo Connectors Directives

Connect REST API endpoints to GraphQL subgraphs by using declarative schema directives

This reference describes the subgraph schema directives that define and connect REST API endpoints to GraphQL fields.

  • @connect describes how to get the data for a GraphQL field from a REST endpoint. Each instance of @connect is a "Connector."

  • @source defines a reusable configuration for multiple Connectors. For example, this allows you to set a baseURL for multiple relative paths.

note
Refer to the Requirements page to learn the minimum required Federation, build pipeline, and router versions for using Connectors directives.

@connect

A @connect directive defines the API data source of a GraphQL schema field.

When building a Connectors subgraph, every field on the Query and Mutation types must have a @connect directive. Additionally, @connect is how you add more fields to object types.

@connect can only retrieve data from HTTP APIs that return JSON data and, optionally, accept a JSON body.

@connect arguments

ArgumentTypeDescription
sourceStringAn optional, reusable configuration, corresponding to @source(name:).
httpConnectHTTP!An object that defines the HTTP methods and URL path templates for the data source.
selectionJSONSelection!Used to map an API's JSON response to GraphQL fields
entityBooleanAllowed for fields on Query only. If set to true, the field acts as an entity resolver in Apollo Federation.
http.bodyJSONSelectionMapping from field arguments to POST, PUT, or PATCH request bodies.
http.headers[HTTPHeaderMapping!]Field-specific headers.

HTTP methods

The http argument accepts exactly one of GET, POST, PUT, PATCH, or DELETE. Specifying none or more than one of these methods causes an error.

If source isn't provided, the URLPathTemplate must be a full URL with an http or https scheme. If source is provided, the URLPathTemplate must be a path relative to the baseURL of the source.

@connect example

GraphQL
@connect example
1extend schema
2  @link(url: "https://specs.apollo.dev/federation/v2.11")
3  @link(url: "https://specs.apollo.dev/connect/v0.2", import: ["@connect"])
4
5type Query {
6  me: User
7    @connect(
8      http: {
9        GET: "https://api.example.com/v1/me"
10        headers: [{ name: "x-api-key", from: "x-api-key" }]
11      }
12      selection: """
13      id
14      name
15      """
16    )
17}
18
19type User {
20  id: ID!
21  name: String!
22}

Valid Connector locations

A summary of the valid uses of @connect within a subgraph schema:

GraphQL
Valid Connector locations
1# Root query type
2type Query {
3  connector1: String @connect(...)
4}
5
6# Root mutation type
7type Mutation {
8  connector2: String @connect(...)
9}
10
11# Object type
12type MyType
13  @connect(...)
14{
15  id: ID!
16  connector3: String @connect(...)
17}

Rules for entity: true

When entity: true is set on a Connector, its field provides an entity resolver for query planning. You must satisfy the following rules to define a valid entity Connector:

  1. The field must be on the Query type.

  2. The arguments of the field must match key fields on the entity type. Commonly, this is the id field, but composite keys are supported.

  3. The output type of the field must be the non-list, nullable, entity type. For example: Product, not Product! or [Product].

  4. The Connector must use the arguments in the URL or request body.

  5. If you define a @key on the type and its resolvable argument is true (which is the default), it must have a corresponding entity: true Connector.

GraphQL
Entity Connector example
1type Query {
2  # 1. field on the Query type
3  product(
4    # 2. arguments match fields in the entity type
5    # composites require an input type
6    id: ID!
7    store: StoreInput!
8  ): Product  # 3. output type is the entity type and nullable
9    @connect(
10      # 4. Connector uses the fields to make the request
11      http: { GET: "http://myapi/store/{$args.store.id}/products/{$args.id}" }
12      selection: "id store { id } name"
13      entity: true
14    )
15}
16
17# 5. the @key fields match the entity Connector arguments
18type Product @key(fields: "id store { id }") {
19  id: ID!
20  store: Store!
21  name: String
22}
23
24type Store {
25  id: ID!
26}
27
28input StoreInput {
29  id: ID!
30}
note
You aren't required to define a @key directive for a type with an entity: true Connector. However, without it, you might need to mark the key fields with @shareable to avoid composition errors when other subgraphs define the same field. (Fields in @key are automatically treated as shareable.)Defining a @key might also reduce the number of hints emitted during composition.

@source

A @source directive defines a shared data source for multiple Connectors.

@source arguments

ArgumentTypeDescription
nameString!A unique identifier for the data source.
httpSourceHTTP!An object that defines the base URL and headers for the data source.
http.baseURLString!The base URL of the data source. All @connect URLs for this source are relative to this base URL. Can be overridden in router configuration.
http.headers[HTTPHeaderMapping!]An array of headers to include in requests to the data source.

@source example

GraphQL
@source example
1extend schema
2  @link(url: "https://specs.apollo.dev/federation/v2.11")
3  @link(
4    url: "https://specs.apollo.dev/connect/v0.2"
5    import: ["@source", "@connect"]
6  )
7  @source(
8    name: "v1"
9    http: {
10      baseURL: "https://api.example.com/v1"
11      headers: [
12        { name: "x-api-key", from: "x-api-key" }
13        { name: "x-caller", value: "apollo-router" }
14      ]
15    }
16  )

Connector specification

note
@connect became applicable on OBJECT types starting in v0.2.
GraphQL
1directive @connect(
2  """
3  Optionally references reusable configuration, corresponding
4  to `@source(name:)`
5  """
6  source: String
7
8  "HTTP configuration"
9  http: ConnectHTTP!
10
11  "Used to map an API's JSON response to GraphQL fields"
12  selection: JSONSelection!
13
14  """
15  Allowed only on fields of `Query`. If set to
16  `true` the field acts as an entity resolver
17  in Apollo Federation
18  """
19  entity: Boolean
20
21  "Optional batch configuration"
22  batch: BatchSettings
23) repeatable on FIELD_DEFINITION
24
25"Only one of {GET,POST,PUT,PATCH,DELETE} is allowed"
26input ConnectHTTP {
27  GET: URLPathTemplate
28  POST: URLPathTemplate
29  PUT: URLPathTemplate
30  PATCH: URLPathTemplate
31  DELETE: URLPathTemplate
32
33  """
34  Header mappings for propagating headers from the
35  original client request to the GraphOS Router, or injecting
36  specific values.
37  """
38  headers: [HTTPHeaderMapping!]
39
40  "Mapping from field arguments to POST|PUT|PATCH request bodies"
41  body: JSONSelection
42}
43
44directive @source(
45  """
46  Unique identifier for the API this directive
47  represents, for example "productsv1"
48  """
49  name: String!
50
51  "HTTP configuration"
52  http: SourceHTTP!
53) repeatable on SCHEMA
54
55input SourceHTTP {
56  """
57  The base scheme, hostname, and path to use,
58  like "https://api.example.com/v2"
59  """
60  baseURL: String!
61
62  """
63  Default header mappings used for all related
64  Connectors. If a Connector specifies its own
65  header mappings, that list is merged with this
66  one, with the Connector's mappings taking precedence
67  when the `name` value matches.
68  """
69  headers: [HTTPHeaderMapping!]
70}
71
72"""
73Defines a header for an HTTP request and where its
74value comes from.
75
76Only one of {from, value} is allowed
77"""
78input HTTPHeaderMapping {
79  "The name of the header to send to HTTP APIs"
80  name: String!
81
82  """
83  The name of the header in the original client
84  request to the GraphOS Router
85  """
86  from: String
87
88  "Optional hard-coded value for non-passthrough headers"
89  value: String
90}
91
92"""
93Settings for batching Connectors that use the `$batch` variable to create
94requests for multiple entities at once.
95"""
96input BatchSettings {
97  """
98  Use this option to limit the number of items in each request. This results in
99  (N / maxSize) + 1 requests to your APIs.
100  """
101  maxSize: Int
102}
103
104"""
105A URL path with optional parameters, mapping to GraphQL
106fields or arguments
107"""
108scalar URLPathTemplate
109
110"A custom syntax for mapping JSON data to GraphQL schema"
111scalar JSONSelection
Feedback

Ask Community