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.
batchBatchSettingsOptional settings for batching Connectors that use the $batch variable to create requests for multiple entities at once.
errorsConnectorErrorsOptional error handling configuration for the Connector. Learn more

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.
errorsConnectorErrorsOptional error handling configuration for related Connectors. Learn more

@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
24  "Optional error handling configuration"
25  errors: ConnectorErrors
26) repeatable on FIELD_DEFINITION
27
28"Only one of {GET,POST,PUT,PATCH,DELETE} is allowed"
29input ConnectHTTP {
30  GET: URLPathTemplate
31  POST: URLPathTemplate
32  PUT: URLPathTemplate
33  PATCH: URLPathTemplate
34  DELETE: URLPathTemplate
35
36  """
37  Header mappings for propagating headers from the
38  original client request to the GraphOS Router, or injecting
39  specific values.
40  """
41  headers: [HTTPHeaderMapping!]
42
43  "Mapping from field arguments to POST|PUT|PATCH request bodies"
44  body: JSONSelection
45}
46
47directive @source(
48  """
49  Unique identifier for the API this directive
50  represents, for example "productsv1"
51  """
52  name: String!
53
54  "HTTP configuration"
55  http: SourceHTTP!
56
57  "Optional error handling configuration for all Connectors for this source"
58  errors: ConnectorErrors
59) repeatable on SCHEMA
60
61input SourceHTTP {
62  """
63  The base scheme, hostname, and path to use,
64  like "https://api.example.com/v2"
65  """
66  baseURL: String!
67
68  """
69  Default header mappings used for all related
70  Connectors. If a Connector specifies its own
71  header mappings, that list is merged with this
72  one, with the Connector's mappings taking precedence
73  when the `name` value matches.
74  """
75  headers: [HTTPHeaderMapping!]
76}
77
78"""
79Defines a header for an HTTP request and where its
80value comes from.
81
82Only one of {from, value} is allowed
83"""
84input HTTPHeaderMapping {
85  "The name of the header to send to HTTP APIs"
86  name: String!
87
88  """
89  The name of the header in the original client
90  request to the GraphOS Router
91  """
92  from: String
93
94  "Optional hard-coded value for non-passthrough headers"
95  value: String
96}
97
98"""
99Settings for batching Connectors that use the `$batch` variable to create
100requests for multiple entities at once.
101"""
102input BatchSettings {
103  """
104  Use this option to limit the number of items in each request. This results in
105  (N / maxSize) + 1 requests to your APIs.
106  """
107  maxSize: Int
108}
109
110input ConnectorErrors {
111  """
112  Use this to configure the "message" field of the top-level GraphQL error that
113  occurs when this Connector fails.
114  """
115  message: JSONSelection
116
117  """
118  Use this to configure the "extensions" object of the top-level GraphQL error
119  that occurs when this Connector fails.
120  """
121  extensions: JSONSelection
122}
123
124"""
125A URL path with optional parameters, mapping to GraphQL
126fields or arguments
127"""
128scalar URLPathTemplate
129
130"A custom syntax for mapping JSON data to GraphQL schema"
131scalar JSONSelection
Feedback

Ask Community