Apollo Connectors for REST APIs

Apollo Connectors are a declarative way for developers to integrate REST services into a GraphQL ecosystem. By defining REST API integrations in GraphQL schemas, you can orchestrate calls across your connected APIs and other services to produce a single response from a federated GraphQL API.

Benefits of connectors

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

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

  • Before connectors, you needed a separate GraphQL service and resolver code to integrate REST services into your graph.

  • Connectors removes the need to create GraphQL APIs that are nothing more than passthrough services to REST APIs.

  
  
  

• Incorporates the security, scalability, observability, and other inherent benefits of GraphOS. Connectors are the quickest way to integrate your APIs with a federated graph and gain the benefits of the GraphOS ecosystem.

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 transform and compose the results into a single response.

Connector example

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

{
  "products": [
    {
      "id": 1,
      "name": "Lunar Rover Wheels",
      "createdAt": 1636742972000,
      "updatedAt": 1636742972000,
      "description": "Designed for traversing the rugged terrain of the moon, these wheels provide unrivaled traction and durability. Made from a lightweight composite, they ensure your rover is agile in challenging conditions.",
      "slug": "lunar-rover-wheels",
    },
    {
      "id": 2,
      "name": "Zero-Gravity Moon Boots",
      "createdAt": 1636742972000,
      "updatedAt": 1636742972000,
      "description": "Experience weightlessness with our Zero-Gravity Moon Boots! Specifically designed to provide comfort and support for lunar explorers, these boots are perfect for hopping around on the moon's surface.",
      "slug": "zero-gravity-moon-boots",
    },
    /// ...
  ]
}

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

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

type Product {
  id: ID!
  name: String!
}

This schema implements the Query.products field using the /products endpoint and maps the id and name values to fields of the same name on the Product type. Notice that the /products endpoint returns many more fields than id, and name. With connectors, you can select and return only the ones you need.

Where connectors work best

Apollo Connectors are designed to work with a wide variety of APIs, providing a simple, declarative way to fetch and transform data without custom code. They work particularly well when you want to expose existing APIs as part of a unified GraphQL API without complex transformations. For example, connectors can seamlessly retrieve product details from a REST API, transform them, and make them available alongside data from other sources.

Connectors aren't the best fit when you need them to perform business logic to overhaul or aggregate your data into a unified GraphQL schema. For instance, aggregating all reviews to calculate an average rating is more efficient in a database rather than via connectors transformations. For more information, consult the detailed list of limitations.

Fortunately, connectors and Apollo Federation work seamlessly 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.

Next steps

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

• Follow the Connectors Quickstart to create your first connector.

• If you already know the basics of creating a connector, check out these common usage patterns or dive deeper into these connectors essentials:

  • Making HTTP requests

  • Mapping GraphQL responses

  • Working with GraphOS Router

• Want to see how others are using connectors? Check out the Apollo Connectors Community