Making HTTP Requests

Apollo Connectors provide a declarative way to integrate REST API calls into your graph using the @connect and @source directives in your schemas. In this guide, you'll learn the basics of making HTTP requests with Apollo Connectors.

Overview

Every Connector needs three things to make an HTTP request:

1. The HTTP method (GET, POST, etc.)

2. The URL to send the request to

3. A selection mapping that describes how to handle the response

You define 1 and 2 with the http argument of the @connect directive and 3 with the selection argument.

The most basic Connector looks something like this:

1type Query {
2  products: [Product]
3    @connect(
4      http: { GET: "https://ecommerce.demo-api.apollo.dev/products" }
5      selection: "id"
6    )
7}

This Connector makes a GET request to https://ecommerce.demo-api.apollo.dev/products and makes the id field available in GraphQL queries.

Basic example Connectors

Example GET request

1type Query {
2  products: [Product]
3    @connect(
4      http: { GET: "https://myapi.dev/products" }
5      selection: "id"
6    )
7}

Example POST request with body

Requests can also include bodies when using a POST, PUT, or PATCH method.

1type Mutation {
2  createProduct(name: String!): Product
3    @connect(
4      http: {
5        POST: "https://myapi.dev/products"
6        body: "name: $args.name"
7      }
8      selection: "id"
9    )
10}

Learn more about creating request bodies with Connectors.

Example PUT request with path parameter

URLs can contain dynamic expressions for setting path or query parameters.

1type Mutation {
2  setProduct(id: ID!, name: String!): Product
3    @connect(
4      http: {
5        PUT: "https://myapi.dev/products/{$args.id}"
6        body: """
7        {
8          name: $args.name,
9          description: $args.description,
10          price: $args.price,
11          inventory: $args.inventory
12        }
13        """
14      }
15      selection: "id"
16    )
17}

Learn more about using dynamic expressions with Connectors.

Example PATCH request with query parameter

1type Mutation {
2  updateProduct(id: ID!, name: String!): Product
3    @connect(
4      http: {
5        PATCH: "https://myapi.dev/products/{$args.id}?name={$args.name}"
6      }
7      selection: "id"
8    )
9}

Learn more about setting query parameters with Connectors.

Example DELETE request

1type Mutation {
2  deleteProduct(id: ID!): Product
3    @connect(
4      http: {
5        DELETE: "https://myapi.dev/products/{$args.id}"
6      }
7      selection: "id"
8    )
9}

Sharing configuration with @source

You can use the @source directive to share a partial URL and headers with multiple Connectors.

Source definition

To define a @source:

1extend schema
2  @link(
3    url: "https://specs.apollo.dev/connect/v0.1",
4    import: ["@connect", "@source"]
5  )
6  @source(
7    name: "myapi"
8    http: {
9      baseURL: "https://myapi.example.com/v1?client=router"
10      headers: [{ name: "X-API-Key", value: "{$config.api_key}" }]
11    }
12  )

1. Import the @source directive from the Connectors @link. (line 4 above)

2. Apply the @source directive to the schema. (lines 6-12 above)

   • Define a baseURL.

   • Optionally define headers, which can't contain $this or $args.

Source usage

To use a @source:

1
2type Query {
3  products(first: Int = 10): [Product]
4    @connect(
5      source: "myapi"
6      http: {
7        GET: "/products?first={$args.first}",
8        headers: [{ name: "X-Product-Type", from: "Product-Type" }]
9      }
10      selection: "id"
11    )
12}

1. Set the source field in each @connect directive that should use the shared configuration. Use the name defined in source definition.

2. Use a partial URL in the @connect directive containing only the path and query parameters (no scheme, host, etc.).

3. Define headers in @connect to override headers from the @source with the same name.

The Connector request above resolves to https://myapi.example.com/v1/products?client=router&first=10. It includes the X-API-Key header from the @source configuration and the X-Product-Type header from the @connect configuration.

Additional resources

For crafting more complex requests, refer to in-depth pages on each part of the HTTP request:

• URL, including query parameters and path segments

• Headers

• Body