Apollo Connectors for REST APIs

Apollo Connectors are a declarative programming model for GraphQL, allowing you to plug your existing REST services directly into your graph. Once integrated, client developers gain all the benefits of GraphQL, and API owners gain all the benefits of GraphOS, including incorporation into a supergraph for a comprehensive, unified view of your organization's data and services.

Benefits of connectors

• With connectors, you no longer need a separate GraphQL service and resolver code to integrate REST services into your graph. This simplifies integrating GraphQL APIs that are nothing more than passthrough services to REST APIs.

• Connectors leverage the power of Apollo Federation to efficiently orchestrate calls to multiple services and compose the results into a single response.

• Connectors are declarative, so you can define your REST integration in your schema and let the GraphOS Router handle the rest.

How do connectors work?

To connect a REST service to your graph, you write a GraphQL schema for the service. Instead of writing resolver code, you add connector directives to the schema. The directives declare which REST endpoints to use for fields.

GraphOS Router uses the schema and directives to plan and orchestrate calls to REST endpoints and compose the results into a single response.

Connector example

Suppose you have a REST API that lets you GET all users at the /users endpoint. Making a GET request to that endpoint yields a JSON response that looks like this:

1{
2  "results": [
3    {
4      "id": "1",
5      "name": "Jane Doe"
6    },
7    {
8      "id": "2",
9      "name": "Sofia Nguyen"
10    },
11    {
12      "id": "3",
13      "name": "John Gonzales"
14    }
15  ]
16}

You could connect your /users endpoint to your graph by writing a schema that looks something like this:

1type Query {
2  users: [User]
3    @connect(
4      http: { GET: "https://api.example.com/users" }
5      selection: """
6      $.results {
7        id
8        name
9      }
10      """
11    )
12}
13
14type User {
15  id: ID!
16  name: String!
17}

This schema implements the Query.users field using the /users endpoint and maps the id and name values to fields of the same name on the User type.

When your APIs aren't a good fit for connectors

Apollo Connectors are designed to work with a wide variety of APIs, but they might not be the best solution for all use cases. Connectors aren't a good fit when you need business logic to transform or aggregate data from your endpoints in order for the data to compose cleanly into a unified GraphQL schema.

Fortunately, connectors and Apollo Federation work wonderfully together. You can combine GraphQL subgraphs with connectors to add business logic to your subgraph alongside declarative data fetching. For example, if you have an API that returns a list but doesn't support filtering, you can use a resolver to fetch and filter the results and let the connector handle the details.

For a detailed list of limitations, refer to the Preview Limitations.

Next steps

Depending on your goals, you have a few options for learning more:

• Follow the Connectors Quickstart to create your first connector.

• Learn Common Patterns for developing with connectors.

• Learn about Making HTTP Requests with your connectors.

• Refer to Working with Federation to learn how connectors interact with entities and other features of Apollo Federation.

• Refer to the Directives Reference for directive usage details.