Apollo Connectors Directives

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

Preview
Apollo Connectors are currently in public preview. To get started, you need an Apollo account with a GraphOS Trial or Enterprise plan.

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.

@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.10")
3  @link(url: "https://specs.apollo.dev/connect/v0.1", 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  id: ID!
14  connector3: String @connect(...)
15}

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.10")
3  @link(
4    url: "https://specs.apollo.dev/connect/v0.1"
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

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) repeatable on FIELD_DEFINITION
21
22"Only one of {GET,POST,PUT,PATCH,DELETE} is allowed"
23input ConnectHTTP {
24  GET: URLPathTemplate
25  POST: URLPathTemplate
26  PUT: URLPathTemplate
27  PATCH: URLPathTemplate
28  DELETE: URLPathTemplate
29
30  """
31  Header mappings for propagating headers from the
32  original client request to the GraphOS Router, or injecting
33  specific values.
34  """
35  headers: [HTTPHeaderMapping!]
36
37  "Mapping from field arguments to POST|PUT|PATCH request bodies"
38  body: JSONSelection
39}
40
41directive @source(
42  """
43  Unique identifier for the API this directive
44  represents, for example "productsv1"
45  """
46  name: String!
47
48  "HTTP configuration"
49  http: SourceHTTP!
50) repeatable on SCHEMA
51
52input SourceHTTP {
53  """
54  The base scheme, hostname, and path to use,
55  like "https://api.example.com/v2"
56  """
57  baseURL: String!
58
59  """
60  Default header mappings used for all related
61  connectors. If a connector specifies its own
62  header mappings, that list is merged with this
63  one, with the connector's mappings taking precedence
64  when the `name` value matches.
65  """
66  headers: [HTTPHeaderMapping!]
67}
68
69"""
70Defines a header for an HTTP request and where its
71value comes from.
72
73Only one of {from, value} is allowed
74"""
75input HTTPHeaderMapping {
76  "The name of the header to send to HTTP APIs"
77  name: String!
78
79  """
80  The name of the header in the original client
81  request to the GraphOS Router
82  """
83  from: String
84
85  "Optional hard-coded value for non-passthrough headers"
86  value: String
87}
88
89"""
90A URL path with optional parameters, mapping to GraphQL
91fields or arguments
92"""
93scalar URLPathTemplate
94
95"A custom syntax for mapping JSON data to GraphQL schema"
96scalar JSONSelection
Feedback

Forums