Apollo Connectors Quickstart

Follow this guide to create a GraphQL API that connects to the JSONPlaceholder REST API using Apollo Connectors.

If you run into any issues, check out our troubleshooting tips for help.

Create the example graph

Create a new GraphOS account.

If your organization doesn't have any graphs yet, click Connect a REST API.

If you already have existing graphs, click the arrow next to Create a new graph, then click Create a new connectors supergraph.

Enter a graph project name and graph ID. Select posts as the example subgraph. Then click Create graph.

After a few moments, you'll get instructions for setting up your local development environment. Follow those instructions, you should end up with rover dev running in your terminal, and a supergraph.yaml and posts.graphql file in your project. The last step brings you back to this quickstart guide.

Your terminal should look something like this:

APOLLO_KEY=... \
APOLLO_GRAPH_REF=... \
APOLLO_ROVER_DEV_ROUTER_VERSION=2.0.0-preview.3 \
rover dev --supergraph-config supergraph.yaml

supergraph config loaded successfully
warning: Do not run this command in production! It is intended for local development only.
==> Watching posts.graphql for changes
WARN: Connector debugging is enabled, this may expose sensitive information.
==> your supergraph is running! head to http://localhost:4000 to query your supergraph
successfully composed with version 2.10.0-preview.3

Connectors only work with the latest preview release of the router (2.0.0-preview.3). The APOLLO_ROVER_DEV_ROUTER_VERSION variable is required to use it from rover dev. Your router should be updated at the same time as the federation_version in your supergraph.yaml file.

Explore your first connector

Let's take a quick look at the posts.graphql file to see how connectors work.

1. These @link directives enable the latest versions of federation and connectors.

   GraphQL

   posts.graphql

   copy

   1extend schema
   2  @link(url: "https://specs.apollo.dev/federation/v2.10")
   3  @link(
   4    url: "https://specs.apollo.dev/connect/v0.1"
   5    import: ["@connect", "@source"]
   6  )

2. The @source directive creates a reusable configuration that each connector can reference. In this case, only baseURL is set for the JSONPlaceholder API, but you can also add headers here.

   GraphQL

   posts.graphql

   copy

   1@source(
   2  name: "jsonPlaceholder"
   3  http: {
   4    baseURL: "https://jsonplaceholder.typicode.com/"
   5  }
   6)

3. Post is the standard GraphQL type that we're looking to return.

   GraphQL

   posts.graphql

   copy

   1type Post {
   2  id: ID!
   3  body: String
   4  title: String
   5}

4. The Query type has a posts field that the @connect directive implemented. source: "jsonPlaceholder" refers to the @source from earlier, http sets the method and path for the request, and selection maps the REST API's JSON response to the GraphQL fields.

   GraphQL

   posts.graphql

   copy

   1type Query {
   2  posts: [Post]
   3    @connect(
   4      source: "jsonPlaceholder"
   5      http: { GET: "/posts" }
   6      selection: """
   7      id
   8      title
   9      body
   10      """
   11    )
   12}

That's it—a fully functional GraphQL API built on connectors!

Run a test query

1. In a browser, go to http://localhost:4000 to open Apollo Sandbox, which was launched with rover dev from the setup instructions.

2. In Apollo Sandbox's Explorer, copy and paste the following query to get all posts.

   GraphQL

   Example Explorer Query

   copy

   query Posts {
     posts {
       id
       body
       title
     }
   }

3. Run the query and check the response.

You should see post data returned from the REST API.

Let's create a second connector that uses arguments.

Create a connector with arguments

1. Add a new post field to the root Query that requires an argument called id. You can use arguments as path and query parameters as well as in the request body.

   GraphQL

   posts.graphql

   copy

   1type Query {
   2  posts: [Post]
   3    @connect(# -- snip -- #)
   4
   5  post(id: ID!): Post
   6    @connect(
   7      source: "jsonPlaceholder"
   8      http: { GET: "/posts/{$args.id}" }
   9      selection: """
   10      id
   11      title
   12      body
   13      """
   14    )
   15}

2. Run a new query in Explorer to get a single post by id.

   GraphQL

   Explorer

   copy

   1query Post {
   2  post(id: "1") {
   3    id
   4    title
   5    body
   6  }
   7}

   You should see results for just a single post.

Congratulations! You've successfully run test queries using connectors.

Next steps

• Get more hands-on experience with Apollo Connectors with an interactive tutorial.

• Refer to Working with Federation to learn how you can use connectors with Apollo Federation.

• Refer to the Directives reference for directive usage details.

• Let us know how you're using connectors in the Apollo Community.