Common Usage Patterns for Apollo Connectors

Apollo Connectors provide versatile options for integrating your REST APIs into your graph. The following are some common patterns.

Providing root fields

The most common use of connectors is implementing Query and Mutation fields in your GraphQL Schema.

Implementing Query fields

In a GraphQL schema, the Query type defines the entry points for reading data from a GraphQL schema. It acts as the root type that clients use to request specific fields and traverse the graph.

Example connector for Query type

In the connectors quickstart, the example connector connects a products listing endpoint (GET /products) to the Query.products field.

type Query {
  products: [Product]
    @connect(
      source: "ecomm"
      http: { GET: "https://ecommerce.demo-api.apollo.dev/products" }
      selection: """
      $.products {  
        id
        name
        description
      }
      """
    )
}

This connector enables GraphQL queries like this:

query Products {
  products {
    id
    name
    description
  }
}

Implementing Mutation fields

In a GraphQL schema, the Mutation type defines the entry points for modifying data. It serves as the root type for operations that create, update, or delete data, allowing clients to make structured changes to the graph.

Example connector for Mutation type

The following connectors example connects a createProduct mutation to an endpoint for creating a new endpoint (POST /products).

type Mutation {
  createProduct(input: CreateProductInput): CreateProductPayload
    @connect(
      http: {
        POST: "https://myapi.dev/products"
        body: """
        $args.input {
          name
          price
        }
        """
      }
    )
}

input CreateProductInput {
  name: String!
  price: Int!
}

The @connect directive's http.body argument lets you use the connectors mapping language to construct request bodies.

This connectors enables GraphQL mutations like this:

mutation {
  createProduct(input: { name: "Lunar Excavator", price: 1200 }) {
    product {
      name
      price
    }
  }
}

Pagination

If your API supports pagination, for example, by supporting limit and offset query parameters, you can expose that functionality in your schema by defining field arguments and using them in your connector URLs. In addition, you can map pagination metadata like total to fields in your schema.

Example connector for pagination

For example, see this example response to a /products endpoint that accepts limit and offset parameters and returns metadata in a summary object.

1{
2  "products": [
3    {
4      "id": 11,
5      "name": "Lunar Excavation Device",
6      "createdAt": 1636742972000,
7      "updatedAt": 1636742972000,
8      "description": "Excavate lunar soil with precision using this Lunar Excavation Device! The rugged build allows for optimal digging and sample collection from the moon's surface.",
9      "slug": "lunar-excavation-device",
10      "tags": [
11        {
12          "tagId": "engineering",
13          "name": "Engineering"
14        },
15        {
16          "tagId": "excavation",
17          "name": "Excavation"
18        },
19        {
20          "tagId": "moon",
21          "name": "Moon"
22        }
23      ],
24      "category": "Mining Equipment",
25      "availability": "AVAILABLE"
26    },
27    // ...
28    {
29      "id": 20,
30      "name": "Solar-Powered Space Suit",
31      "createdAt": 1675200000000,
32      "updatedAt": 1675200000000,
33      "description": "Eco-friendly space suit equipped with solar panels for charging all your devices while exploring the cosmos. Made from breathable and flexible materials for maximum comfort.",
34      "slug": "solar-powered-space-suit",
35      "tags": [
36        {
37          "tagId": "9",
38          "name": "Apparel"
39        },
40        {
41          "tagId": "10",
42          "name": "Eco-Friendly"
43        }
44      ],
45      "category": "Space Gear",
46      "availability": "AVAILABLE"
47    }
48  ],
49  "summary": {
50    "total": 30
51  }
52}

Given this response shape, you can create a connector with the following path and selection mapping:

type ProductsResult {
  results: [Product]
  totalCount: Int
}

type Query {
  products(limit: Int, offset: Int): ProductsResult!
    @connect(
      http: {
        GET: "https://ecommerce.demo-api.apollo.dev/products?limit={$args.limit}&offset={$args.offset}"
      }
      selection: """
      results: $.products {
        id
        name
        description
      }
      totalCount: summary.total
      """
    )
}

This connector enables GraphQL queries like this:

query Products {
  products(limit: 10, offset: 10) {
  results {
    id
    name
  }
  totalCount
  }
}

This query retrieves the id and name of products 11 - 20 and the total number of products.

Additional resources

See selection mapping examples and value transformation examples for other common connectors usage patterns.

Working with entities

Connectors are particularly valuable for combining data from different APIs into a single, unified entity. For resources on working with entities, refer to:

• The example entity connector in the connectors quickstart

• Working with Federation for more information on using connectors with entities