Odyssey

Voyage I: Federation from Day One

Intro to FederationProject setupAgreeing on a schemaBuilding out the subgraphsManaged federation & the supergraphPublishing the subgraphs with RoverHow the router resolves dataRouter configuration and UplinkConnecting data using entitiesDefining an entityEntities and the query planReferencing an entityContributing to an entityPutting it all together
14. Putting it all together
4m

Overview

We now have a complete schema for FlyBy's supergraph. It's time to put all of the pieces together and make sure our backend server meets all the frontend requirements we set at the start!

In this lesson, we will:

  • Run the FlyBy client, which will query our supergraph
  • Check that all the GraphQL operations used in the frontend code work as expected

Returning to the frontend

You might have noticed that we haven't reviewed any of the frontend code. Our initial meeting with the frontend team set the expectations for the data our backend should provide, but since that time we haven't needed to get in the way of their work to implement the UI. Let's see what they've built!

Launching the client

Open up a new terminal window and navigate to the client directory. Run the following command to install the packages and launch the app:

On MacOS/Linux
npm install && npm start
On Windows
npm install; npm start

In the browser, navigate to http://localhost:3000 to see the FlyBy homepage.

Oh no! We can see that the page is showing an error: Failed to fetch.

http://localhost:3000
The FlyBy homepage UI, showing an error that it failed to fetch.

But wait, we queried our supergraph perfectly fine using Studio! So why is the client unable to connect?

Cross-origin resource sharing (CORS) and the router

Our client can't connect because of CORS, which stands for cross-origin resource sharing. CORS is a protocol that enables your server to specify which websites can talk to it.

By default, the GraphOS Router enables only Studio (https://studio.apollographql.com) to connect to your server.

This means we'll need to configure the router to also allow requests from http://localhost:3000 (where our client is running) while we're testing it locally.

Note: You can read more about CORS (and why it's important) in the Apollo documentation.

✏️ Configuring CORS settings

There are many different ways to configure the CORS options for the router. For FlyBy, we'll use the origins property to explicitly specify which client URLs are allowed to connect to the router.

Note: You can learn more about other supported CORS configurations in the Apollo documentation.

  1. In the router directory, create a file called config.yaml. This file will let us customize the router when it starts up.

  2. Add the following configuration. It uses the origins key and specifies that both Studio and the locally-running client should be able to connect to the router.

    config.yaml
    cors:
      origins:
        - http://localhost:3000 # Allows any locally-running client to run against your Router
        - https://studio.apollographql.com # Allows Studio to still run queries against your Router

  3. In the terminal, if your router is still running, stop the process with CTRL+C.

  4. We'll run the router again, but with an additional parameter: the --config flag as well as the path to our config file.

    MacOS / Linux / WSL
    APOLLO_KEY=<APOLLO_KEY> APOLLO_GRAPH_REF=<APOLLO_GRAPH_REF> ./router --config ./config.yaml
    Windows powershell
    $env:APOLLO_KEY="<APOLLO_KEY>"
    $env:APOLLO_GRAPH_REF="<APOLLO_GRAPH_REF>"
    ./router --config ./config.yml

    The router should be running successfully, with console output indicating the port it's running on.

Checking the client

Let's check out the FlyBy homepage again at http://localhost:3000. Alright, we've got data showing!

http://localhost:3000
The FlyBy homepage UI

Our mockups have been brought to life! We can see first hand locations, reviews and submit reviews of our own. Our supergraph is working smoothly for us behind the scenes!

Task!

If an error occurs when loading the client application, we might have missed a step along the way. Here are some troubleshooting tips for getting things up and running:

  • ECONNREFUSED: If the error indicates that a request to either http://localhost:4001 or http://localhost:4002 failed, make sure that both subgraphs are running. Relaunch both subgraphs by opening a new terminal in each subgraph directory, subgraph-locations and subgraph-reviews. Then, run npm start in each.

    http://localhost:3000
    An ECONNREFUSED error indicating one or both subgraphs are not running

  • Failed to Fetch: In the event of a failure to fetch, return to the terminal of the router and make sure that it is running.

    http://localhost:3000
    FlyBy Failed to Fetch error page indicating the router is not running

  • CORS issue: Your browser console message is displaying a CORS message such as "Access to fetch at [URL] from origin http://localhost:3000 has been blocked by CORS policy". To fix this, go back to your router's config.yaml file where you set up the CORS configuration.

    Make sure your file looks like the code below and that there is no slash (/) at the end of the URLs specified.

config.yaml
server:
  cors:
    origins:
      - http://localhost:3000 # Allows any locally-running client to run against your Router
      - https://studio.apollographql.com # Allows Studio to still run queries against your Router
  • 400: Bad Request: This error indicates that a request to the router failed. Open up the network tab in the browser to inspect the failed request. (You might need to reload your page with this tab open!) Use the Preview tab on the request to see the server response, which should provide more detail about where the failure occurred. Make sure to run the rover subgraph publish command detailed in Lesson 5 to push subgraph changes to the Apollo schema registry.
    http://localhost:3000
    A 400 Bad Request error indicating an invalid request

Still having trouble? Visit the Odyssey forums to get help.

Key takeaways

  • Clients request data from a single GraphQL server: the router.
  • The router can set CORS rules to specify which websites can talk to it.
  • We can set up these rules (and other configurations) through the router's config file.

Conclusion

That was an exciting adventure of building a supergraph! We've reached the end of the course and covered many of the principles we can use to set up a new project with a supergraph.

We learned about why we would pick Apollo Federation right from the start to build a modular GraphQL API that can scale as our product and development teams grow.

We used the managed federation workflow to publish our subgraphs and visualize the composed supergraph schema in Studio.

Finally, we took a deep dive into how to create entities to reference and contribute new fields to types across subgraphs.

And along the way, we brought all this together to create a supergraph that powers the FlyBy experience.

Thanks for joining us on our first voyage into Apollo Federation and the supergraph. We look forward to seeing you in the next course, Voyage II: Federating the Monolith!

Previous

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.

              supergraph

              A unified, federated graph composed of separate GraphQL APIs using Apollo Federation. Enables a microservices architecture that exposes a unified GraphQL API to clients.

              query

              A request for specific data from a GraphQL server. Clients define the structure of the response, enabling precise and efficient data retrieval.

              supergraph

              A unified, federated graph composed of separate GraphQL APIs using Apollo Federation. Enables a microservices architecture that exposes a unified GraphQL API to clients.

              GraphQL

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

              operations

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

              launch

              The process of applying a set of updates to a supergraph. Launches are usually triggered by making changes to one of your published subgraph schemas.

              supergraph

              A unified, federated graph composed of separate GraphQL APIs using Apollo Federation. Enables a microservices architecture that exposes a unified GraphQL API to clients.

              GraphOS Router

              A scalable runtime for supergraphs that's fully integrated with GraphOS and based on the Apollo Router Core. Can be cloud- or self-hosted.

              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.

              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.

              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.

              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.

              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.

              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.

              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.

              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.

              supergraph

              A unified, federated graph composed of separate GraphQL APIs using Apollo Federation. Enables a microservices architecture that exposes a unified GraphQL API to clients.

              subgraphs

              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.

              launch

              The process of applying a set of updates to a supergraph. Launches are usually triggered by making changes to one of your published subgraph schemas.

              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.

              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.

              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.

              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.

              GraphQL server

              A server that contains a GraphQL schema and can resolve client-requested operations that are executed against that schema.

              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.

              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.

              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.

              supergraph

              A unified, federated graph composed of separate GraphQL APIs using Apollo Federation. Enables a microservices architecture that exposes a unified GraphQL API to clients.

              Apollo Federation

              Apollo’s implementation of GraphQL Federation—an architecture for orchestrating multiple APIs into a single GraphQL API.

              GraphQL

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

              managed federation

              A managed approach to supergraph composition and deployment. With managed federation, subgraphs publish their schemas to GraphOS, which validates, composes, and deploys the supergraph schema.

              subgraphs

              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.

              supergraph schema

              A special type of GraphQL schema that is created by declaratively combining one or more subgraph schemas using the Apollo Federation specification.

              entities

              An object type of Apollo Federation that can be fetched with one or more unique keys. Can resolve its fields from multiple data sources in a federated graph.

              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
              }
              subgraphs

              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.

              supergraph

              A unified, federated graph composed of separate GraphQL APIs using Apollo Federation. Enables a microservices architecture that exposes a unified GraphQL API to clients.

              Apollo Federation

              Apollo’s implementation of GraphQL Federation—an architecture for orchestrating multiple APIs into a single GraphQL API.

              supergraph

              A unified, federated graph composed of separate GraphQL APIs using Apollo Federation. Enables a microservices architecture that exposes a unified GraphQL API to clients.

              NEW COURSE ALERT

              Introducing Apollo Connectors

              Connectors are the new and easy way to get started with GraphQL, using existing REST APIs.

              Say goodbye to GraphQL servers and resolvers—now, everything happens in the schema!

              Take the course