How to Federate Fastio API with GraphQL Federation

Think of GraphQL Federation as a way to merge several APIs into one. Instead of forcing your frontend to talk to five different backends, you use a single gateway. This gateway knows exactly where to find each piece of data, whether it's a file from Fastio or a user profile from your own database.

The gateway handles the heavy lifting of routing queries across subgraphs. Your clients interact with a single schema, so they don't need to know how the backend is split up. This approach has become a standard for teams that want to scale services independently without creating a messy developer experience. Fastio works well as a dedicated storage subgraph within this architecture.

Helpful references: Fastio Workspaces, Fastio Collaboration, and Fastio AI.

The Fastio REST API at api.fast.io/current is built for agentic workflows. It provides endpoints for organizations, workspaces, storage, shares, and AI features.

You'll authenticate using JWT or API keys. Most resources, like workspaces, use multiple-digit IDs. Storage nodes use their own unique IDs for files and folders.

For example, calling GET /current/workspace/{id}/storage/list returns a list of files with previews and metadata. This structured data makes it easy to build GraphQL entity resolvers.

If you're just starting, the free agent tier includes multiple of storage and multiple credits per month. You can find the full documentation at docs.fast.io.

• Node.js 18 or newer.
• A Fastio account and an API key (found in Settings > API Keys).
• Apollo tools, specifically @apollo/subgraph and Apollo Router.
• A basic understanding of GraphQL and REST APIs.

You can sign up for the agent plan at fast.io/storage-for-agents.

First, set up your project and install the necessary dependencies:

npm init -y
npm i @apollo/server @apollo/subgraph graphql axios dotenv

Next, create a schema.graphql file to define your types:

extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.0", import: ["@key", "@shareable"])

type Query {
  workspaces: [Workspace!]!
  workspace(id: ID!): Workspace
}

type Workspace @key(fields: "id") {
  id: ID!
  name: String!
  files: [File!]!
  shares: [Share!]!
}

type File @key(fields: "id") {
  id: ID!
  name: String!
  size: Int!
  previewUrl: String
}

type Share @key(fields: "id") {
  id: ID!
  title: String!
}

Make sure to add your FASTIO_API_KEY to your .env file before moving on.

The core of this integration is converting REST calls into GraphQL responses. We'll use axios to fetch data from the Fastio API and map it to our schema.

In your index.js:

import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { buildSubgraphSchema } from '@apollo/subgraph';
import { readFileSync } from 'fs';
import axios from 'axios';
import dotenv from 'dotenv';

dotenv.config();

const typeDefs = readFileSync('./schema.graphql', 'utf8');
const schema = buildSubgraphSchema([{ typeDefs }]);

const resolvers = {
  Query: {
    workspaces: async () => {
      const res = await axios.get('https://api.fast.io/current/org/me/workspaces/', {
        headers: { Authorization: `Bearer ${process.env.FASTIO_API_KEY}` }
      });
      return res.data.response;
    },
    workspace: async (_, { id }) => {
      const res = await axios.get(`https://api.fast.io/current/workspace/${id}/`, {
        headers: { Authorization: `Bearer ${process.env.FASTIO_API_KEY}` }
      });
      return res.data.response[0];
    }
  },
  Workspace: {
    __resolveReference: async ({ id }) => {
      const res = await axios.get(`https://api.fast.io/current/workspace/${id}/`, {
        headers: { Authorization: `Bearer ${process.env.FASTIO_API_KEY}` }
      });
      return res.data.response[0];
    },
    files: async ({ id }) => {
      const res = await axios.get(`https://api.fast.io/current/workspace/${id}/storage/list?path=root`, {
        headers: { Authorization: `Bearer ${process.env.FASTIO_API_KEY}` }
      });
      return res.data.response.filter(n => n.type === 'file');
    },
    shares: async ({ id }) => {
      const res = await axios.get(`https://api.fast.io/current/workspace/${id}/shares/`, {
        headers: { Authorization: `Bearer ${process.env.FASTIO_API_KEY}` }
      });
      return res.data.response;
    }
  },
  File: {
    __resolveReference: async ({ id, workspaceId }) => {
      const res = await axios.get(`https://api.fast.io/current/workspace/${workspaceId}/storage/details/${id}`, {
        headers: { Authorization: `Bearer ${process.env.FASTIO_API_KEY}` }
      });
      return res.data.response;
    },
    previewUrl: async ({ id, workspaceId }) => {
      const res = await axios.get(`https://api.fast.io/current/workspace/${workspaceId}/storage/preview-url/${id}`, {
        headers: { Authorization: `Bearer ${process.env.FASTIO_API_KEY}` }
      });
      return res.data.response.url;
    }
  }
};

const server = new ApolloServer({ schema, resolvers });
startStandaloneServer(server, { listen: { port: multiple } }).then(({ url }) => console.log(`Subgraph ready at ${url}`));

This code stitches REST responses into your GraphQL types. The __resolveReference function is what allows the gateway to resolve entities across different subgraphs.

Ready for agentic GraphQL workflows?

Fastio free agent tier: 50GB storage, REST API, MCP tools. Federate with your supergraph today. Built for fastio api graphql federation tutorial workflows.

Start Free

Once your subgraph is running, you can combine it with others, such as a user service. You'll use Apollo Router to manage the gateway.

Create a supergraph.yaml file:

homepage: https://studio.apollo.dev
subgraph_url: fastio: http://localhost:4001
### Add more subgraphs here

Then run the following command to compose your schema:

rover supergraph compose supergraph.yaml > schema.graphql

You can then deploy the Router using Docker. When testing your query, it should look something like this:

query {
  workspace(id: "1234567890123456789") {
    name
    files {
      name
      size
      previewUrl
    }
  }
}

If you run into issues, check for composition errors in Rover or verify that your API keys are correct.