Apollo Connectors for REST APIs

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.

Supported versions

The connectors preview requires the following versions of the router and federation:

• router 2.0.0-preview.0

• federation 2.10.0-preview.0

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 Using HTTP Semantics in 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.