Connectors in the GraphQL schema - GraphQL Tutorials

GraphQL meets REST, with Apollo Connectors

Introducing Apollo Connectors Project setup How Connectors work in the schema Defining a @source The @connect directive Debugging Connectors Arguments Orchestration in action Using entities with Connectors Mutations

3. How Connectors work in the schema

3m

(Text covers the exact same content as the video)

Overview

Apollo Connectors transform the way we connect to REST APIs, simplifying API orchestration in a declarative, configuration-first approach.

All of the work happens in the schema. First, we define the types and fields that make up our API. Then, we configure our request to a data source and transform the response to a shape that fits with our schema.

In this lesson, we will:

Learn about two GraphQL directives: @source and @connect.

The `@source` directive

With @source, we define the core information about the data source: its name and details, such as the base URL and any HTTP headers we want to include with the request. We could have multiple data sources in one schema, so defining multiple @source instances helps us easily reuse and refer to which one we need.

Example @source syntax

@source(
  name: "products" # A unique identifier for the data source.
  http: {  # An object that defines the baseURL string and an array of headers for the data source
    baseURL: "https://products.example.com",
    headers: [{ name: "Authorization", from: "Authorization" }] }
)

The `@connect` directive

Next we have the heart of Connectors: the @connect directive.

The @connect directive attaches to a field or object type in the schema. Here, we define the instructions for our request (to get the data) and the response (to map that data to the schema).

The request

To configure the request, we provide @connect with:

A source to connect to
The HTTP method like GET or POST with the specific path to the endpoint
Any additional headers
An optional body payload

Example @connect syntax - request

@connect(
  source: "products"
  http: {
    GET: "/products",
    headers: [
      { name: "Authorization", from: "Authorization" },
      { name: "X-Api-Key", value: "ODYSSEY"}
    ]
  }
  selection: """
  id
  title
  description
  """
)

The response

To configure the response, the Connector needs a selection mapping: how the JSON response maps to the types and fields in our schema.

Sometimes the mapping is simple, one-to-one, where the property names in the response match our schema types and fields exactly.

Other times, we may want to rename properties, dig in a level or two deeper to access a particular value, or work with multiple nested types and fields. All of this happens in the selection property of @connect, explicitly defined and available for everyone on our team to see.

Example @connect syntax - response

@connect(
  source: "products"
  http: {
    GET: "/products",
    headers: [{ name: "Authorization", from: "Authorization" }]
  }
  selection: """
  id: upc
  title
  description
  """
)

And that's it for Connectors in the schema, just directives and configuration.

But where does this schema live, and how do clients actually send their requests to our API? We're missing one piece of the puzzle: the router.

API orchestration with the router

The router acts as the single access point to our API and coordinates the orchestration for us. It receives requests from a client, then follows the instructions in our schema to connect to the relevant data sources directly.

Now if you're using GraphQL Federation, you might be thinking: "This router thing sounds familiar". And you'd be right! This is the same router we can find in a federated architecture, that routes parts of a GraphQL operation to the subgraph responsible for it. We can mix and match subgraphs and Connectors.

All we need to do is give the router our schema, and it takes care of the rest!

Practice

What is the purpose of the @source directive?

To configure the router to handle API requests.To specify core information about a data source, such as its base URL and headers.To define how JSON responses map to schema fields.To define the HTTP method and path for an API endpoint.

What does the @connect directive do?

Defines the core information about a data source.Configures the router to process API requests.Defines request instructions and response mappings for root or object fields in the schema.Connects fields from one schema to fields in a different schema file.

Key takeaways

The @source directive sets up data sources, including their name, base URL, and any necessary HTTP headers.
The @connect directive attaches to a field or object type, where we can define instructions for our request to and map the response from a REST API endpoint.
The router serves as the single entry point to the API, taking care of the orchestration for us.

Up next

Let's jump into the schema and put these directives to work! Coming up next, we'll use @source to define our REST API data source.

Share your questions and comments about this lesson

Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.

directive

A GraphQL annotation for a schema or operation that customizes request execution. Prefixed with @ and may include arguments. For example, the @lowerCase directive below can define logic to return the username field in lowercase:

type User {
  username: String! @lowerCase
}

directive

A GraphQL annotation for a schema or operation that customizes request execution. Prefixed with @ and may include arguments. For example, the @lowerCase directive below can define logic to return the username field in lowercase:

type User {
  username: String! @lowerCase
}

field

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

object type

A type in a GraphQL schema that has one or more fields. User is an object type in the following example:

type User {
  name: String!
}

router

The single access point for a federated GraphQL architecture. It receives incoming operations and intelligently routes them across component services before returning a unified response.

directives

A GraphQL annotation for a schema or operation that customizes request execution. Prefixed with @ and may include arguments. For example, the @lowerCase directive below can define logic to return the username field in lowercase:

type User {
  username: String! @lowerCase
}

Apollo Connectors

Apollo Connectors are a declarative programming model for GraphQL, allowing you to plug your existing REST services directly into your graph.

API orchestration

The process of combining and coordinating multiple APIs. Includes sequencing API calls, transforming data, and managing security requirements.

fields

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

GraphQL

An open-source query language and specification for APIs that enables clients to request specific data, promoting efficiency and flexibility in data retrieval.

directives

A GraphQL annotation for a schema or operation that customizes request execution. Prefixed with @ and may include arguments. For example, the @lowerCase directive below can define logic to return the username field in lowercase:

type User {
  username: String! @lowerCase
}

directive

A GraphQL annotation for a schema or operation that customizes request execution. Prefixed with @ and may include arguments. For example, the @lowerCase directive below can define logic to return the username field in lowercase:

type User {
  username: String! @lowerCase
}

directive

A GraphQL annotation for a schema or operation that customizes request execution. Prefixed with @ and may include arguments. For example, the @lowerCase directive below can define logic to return the username field in lowercase:

type User {
  username: String! @lowerCase
}

field

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

object type

A type in a GraphQL schema that has one or more fields. User is an object type in the following example:

type User {
  name: String!
}

fields

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

fields

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

fields

A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

type Author {
  # id, firstName, and lastName are all fields of the Author type
  id: Int!
  firstName: String
  lastName: String
}

directives

A GraphQL annotation for a schema or operation that customizes request execution. Prefixed with @ and may include arguments. For example, the @lowerCase directive below can define logic to return the username field in lowercase:

type User {
  username: String! @lowerCase
}

router

The single access point for a federated GraphQL architecture. It receives incoming operations and intelligently routes them across component services before returning a unified response.

GraphQL Federation

An architecture for combining multiple APIs into a single GraphQL API. Implemented by Apollo Federation.

router

The single access point for a federated GraphQL architecture. It receives incoming operations and intelligently routes them across component services before returning a unified response.

operation

A single query, mutation, or subscription that clients send to a GraphQL server to request or manipulate data.

subgraph

A service in a federated GraphQL architecture. Acts as a module for a supergraph. Includes both GraphQL services and REST services integrated via Apollo Connectors.

router

The single access point for a federated GraphQL architecture. It receives incoming operations and intelligently routes them across component services before returning a unified response.