REGISTER NOW FOR THE KONG AGENTIC ERA WORLD TOUR GOVERN A2A TRAFFIC WITH KONG'S NEW AGENT GATEWAY WHY GARTNER’S “CONTEXT MESH” CHANGES EVERYTHING DON’T MISS API + AI SUMMIT 2026 SEPT 30 – OCT 1
We're Entering the Age of AI Connectivity [Read more](/blog/news/the-age-of-ai-connectivity)Read moreProducts & Agents:
[Engineering](/blog/engineering)Engineering
September 13, 2023
11 min read

# Building Dynamic Aggregate APIs with GraphQL

Rick Spurgeon
Product Engineer, Kong

[API Summit 2023 banner](https://konghq.com/conferences/kong-summit)API Summit 2023 banner

[Domain-driven designs](https://martinfowler.com/bliki/DomainDrivenDesign.html)Domain-driven designs are popular in organizations that have complex domain models and wish to organize engineering around them. [REST-based](https://konghq.com/blog/learning-center/what-is-restful-api)REST-based architectures are a common choice for implementing the API entry point into these domains. REST-based solutions are straightforward for the API builder and for API consumers concerned with data from a single API. But what about developers tasked with aggregating information across domains? Developers building end-user websites, mobile apps, and internal dashboards are faced with the difficult task of orchestrating data across these domain APIs.

These developers need access to a wide range of data to build a consistent experience for the end-user. Often these developers resort to anti-patterns, like building hand-crafted "back-end for front-end" (BFF) APIs that do complex domain aggregation. These custom BFF APIs are maintenance burdens as they multiply when clients require different aggregate views of the domain information. BFF APIs are often authored in REST and directly expose clients to custom static specifications which are vulnerable to upstream API changes. What these developers need is a dynamic aggregate API to build their applications on top of.

[GraphQL](https://graphql.org/)GraphQL offers a solution to this problem by providing a flexible query design along with a layer of decoupling between clients and the domains that service their data needs.

If you're new to GraphQL, you may want to review [the basics of GraphQL and the base concepts](https://konghq.com/blog/engineering/graphql-from-the-ground-up)the basics of GraphQL and the base concepts in our previous post before proceeding. In this post, we're going to take the next step and look at a functioning GraphQL service that aggregates existing domain APIs and exposes them into a dynamic API for these common use cases.

## Domain REST APIs

In this post, we're going to use a fictitious airline named *KongAir* as our example business use case.

KongAir is a domain-driven technology organization where individual development teams build services and applications focused on their business domains. Teams are free to work in their own languages and technology stacks. APIs are delivered using the REST model, and each service contains an OpenAPI Specification detailing the API behavior. All the source code discussed in this post is available in the public [KongAir](https://github.com/Kong/KongAir)KongAir GitHub repository.

KongAir deploys the domain services on [Kong Konnect](https://docs.konghq.com/konnect/)Kong Konnect, which provides a full API management platform including an API Developer Portal we can use to explore the REST APIs. You can view the developer portal at [https://portal.kong-air.com/](https://portal.kong-air.com/)https://portal.kong-air.com/.

The KongAir *flight-data* team builds APIs that serve public, unsecured data for the airline’s flight routing and schedule. This team builds services in GoLang for its straightforward syntax and high-performance runtime characteristics. The team provides the following services:

The airline's *sales* development team builds services that serve customer-specific needs including personal information and flight booking systems. The sales development team uses NodeJS for its rapid development capabilities and extensive library ecosystem. The team provides these services:

The APIs are also hosted at `api.kong-air.com`, which means we can test the APIs with an API development tool like [Kong Insomnia](https://insomnia.rest/)Kong Insomnia.

We can also query the Routes API on the command line with tools like `curl`:

curl -s https://api.kong-air.com/routes

Now that we have some REST APIs to build on, let's see how to compose them up into a dynamic *experience* API for our application developers.

## GraphQL Experience APIs with Apollo Server

The experience API is built on top of the popular [Apollo Server](https://www.apollographql.com/docs/apollo-server)Apollo Server, which provides us with a complete GraphQL SDK. The full source code for this API is available in the [experience team's folder](https://github.com/Kong/KongAir/tree/main/experience)experience team's folder in the KongAir repository. In the following sections, we'll tease apart the important sections of the code and see how the REST APIs are integrated with a GraphQL service.

### Schemas

As we learned in the [first part of this series](https://konghq.com/blog/engineering/graphql-from-the-ground-up)first part of this series, GraphQL services start with a schema that defines the queries and types available to clients. The KongAir experience API is coded from the perspective of the end user, with a single query named `me` that returns an object of type `Me`. The `Me` object defines all of the information that can be provided about a user including their personal information and current bookings. When making a query to the GraphQL service, applications will provide a bearer token in the `Authorization` header. This token contains a `username` claim in the token body which will be used to identify the user throughout the KongAir system.

[schema.js](https://github.com/Kong/KongAir/blob/main/experience/schema.js)schema.js

type Query {
  me: Me!
}
type Me {
  name: String!
  username: String!
  bookings: [Booking!]!
  information: MyInfo!
}
type Booking {
  ticket_number: String!
  flight: Flight!
  seat: String!
}
type Flight {
  number: String!
  route_id: String!
  route: Route!
  scheduled_departure: String!
  scheduled_arrival: String!
  details: FlightDetails!
}
type Route {
  id: String!
  origin: String!
  destination: String!
  avg_duration: Int!
}
...

The full schema for the KongAir experience API is defined in the [schema.js](https://github.com/Kong/KongAir/blob/main/experience/schema.js)schema.js file and includes the rest of the types available to query in the API.

### Data Sources

GraphQL services work in partnership with upstream data sources. In greenfield projects, you may choose to connect GraphQL directly to databases. Here, we're layering GraphQL onto the existing KongAir domain services. The Apollo SDK provides us with a REST-specific data source library that aids in the integration of upstream APIs by providing convenience functions, error handling, and caching layers. In the [`datasources`](https://github.com/Kong/KongAir/tree/main/experience/datasources)`datasources` folder you will find a separate file for each KongAir domain API we are integrating. For example, the [routes API datasource](https://github.com/Kong/KongAir/blob/main/experience/datasources/routes-api.js)routes API datasource is defined as follows:

const { RESTDataSource } = require('@apollo/datasource-rest');

class RoutesAPI extends RESTDataSource {
  baseURL = process.env.ROUTES_SVC_BASE_URL;

  getRoutes() {
    return this.get('routes');
  }
  getRoute(id) {
    return this.get(`routes/${id}`);
  }
}

module.exports = RoutesAPI;

The JavaScript class extends the `RESTDataSource` and includes a configurable `baseURL` value as well as implementation functions for each resource and HTTP verb combination. At runtime the `baseURL` is paired with the path provided in each implementation function argument to construct the full request URL. You can see how the `RoutesAPI` class aligns with the routes service REST paths from the OpenAPI snippet below ([openapi.yaml](https://github.com/Kong/KongAir/blob/main/flight-data/routes/openapi.yaml)openapi.yaml):

paths:
  "/routes":
    get:
     ...
  "/routes/{id}":
    get:
     ...

In the KongAir system, users are identified by a [JSON Web Token](https://jwt.io/introduction)JSON Web Token (JWT) provided in the request `Authorization` header. KongAir runs [Kong Gateway](https://docs.konghq.com/gateway/latest/)Kong Gateway as the API gateway in front of all services, and uses the [JWT Plugin](https://docs.konghq.com/hub/kong-inc/jwt/)JWT Plugin to authorize requests. The gateway passes the token to the GraphQL service, so when we code the data sources for any secured APIs, we must pass the token through to the upstream REST APIs. More details on token handling in the API will be discussed later in this post. For now, the BookingsAPI class shows the passing through of request authorization headers to the upstream API.

[booking-api.js](https://github.com/Kong/KongAir/blob/main/experience/datasources/bookings-api.js)booking-api.js

const { RESTDataSource } = require('@apollo/datasource-rest');

class BookingsAPI extends RESTDataSource {
  baseURL = process.env.BOOKINGS_SVC_BASE_URL;

  constructor(req, options) {
    super(options);
    this.auth = req.headers.authorization;
  }

  getBookings() {
    return this.get('bookings', {
      headers: { authorization: this.auth }
    });
  }
}

module.exports = BookingsAPI;

The Apollo [documentation on fetching from REST APIs](https://www.apollographql.com/docs/apollo-server/data/fetching-rest)documentation on fetching from REST APIs provides more details on using the library.

### Resolvers

The [Apollo documentation on Resolvers](https://www.apollographql.com/docs/apollo-server/data/resolvers/)Apollo documentation on Resolvers provides us with a precise definition of their purpose:

Apollo Server needs to know how to populate data for every field in your schema so that it can respond to requests for that data. To accomplish this, it uses resolvers.

A resolver is a function that’s responsible for populating the data for a single field in your schema. It can populate that data in any way you define, such as by fetching data from a back-end database or a third-party API.

A resolver is implemented as a JavaScript object with properties that correspond to the GraphQL schema *types*. The property values are functions that retrieve the relevant data, and as the Apollo SDK fulfills a query request, it traverses the schema and invokes the resolver function for each field. When using data sources as described above, we define a resolver that maps the schema type to the corresponding data sources. Here is what the resolver code looks like for the KongAir `Me` experience API:

[resolvers.js](https://github.com/Kong/KongAir/blob/main/experience/resolvers.js)resolvers.js

const resolvers = {
  Query: {
    me: (_, __, { dataSources }) => dataSources.customerAPI.getCustomer()
  },
  Me: {
    bookings: (_, __, { dataSources }) => dataSources.bookingsAPI.getBookings()
  },
  Flight: {
    details: (parent, _, { dataSources }) => {
      return dataSources.flightsAPI.getFlightDetails(parent.number);
    },
    route: (parent, _, { dataSources }) => {
      return dataSources.routesAPI.getRoute(parent.route_id);
    }
  },
};

module.exports = resolvers;

The magic in the Apollo resolver SDK is that for any field that does not have a resolver definition, the SDK defines a default resolver for it. In cases where the data source returns an object with property names that matches the schema property names, the server can map these fields automatically.

For example, in the `Me` schema, a field is defined as `username`, which matches the returned field from the Customer Information API exactly allowing the field to be mapped automatically. Resolving data for more complex objects and relationships between them requires additional logic. For example, let's look at how a user’s `Bookings` are returned from the GraphQL service.

A `Booking` contains a `Flight`, but the Bookings API only returns some of the flight information, not the full flight details. `FlightDetails` are provided by the Flights API, and the `Flight` and `FlightDetails` are related using the `Flight.number` field. Similarly, a `Flight` contains a `Route`, but the `Route` information is provided by the Routes API. A `Flight` and a `Route` are linked by the `Flight.route_id` field.

When a request comes into the GraphQL service, the Apollo SDK traverses the resolvers' structure to populate the data, this is called the *resolver chain*. Initially, the SDK will invoke the resolver defined for the specific Query that was invoked, `me` in our example above. From that resolver's return value, the SDK will traverse each field and either invoke a defined resolver function or attempt to use the default resolver as explained earlier. The resolver functions accept [arguments](https://www.apollographql.com/docs/apollo-server/data/resolvers/#resolver-arguments)arguments, the first of which is `parent`, which contains the previous result in resolver in the chain. The `parent` instance is analogous to a parent in an object-oriented data model. This allows us to obtain related information from different APIs using parent / child relationships in the data. In our example, the flight details are returned from the Flights API using the `parent.number` field, which is defined as the `Booking.flight.number` field in the GraphQL schema.

The full code for the resolver is defined in the [resolvers.js](https://github.com/Kong/KongAir/blob/main/experience/resolvers.js)resolvers.js file.

### Bringing it together

The entry point of the GraphQL service is defined in the [index.js](https://github.com/Kong/KongAir/blob/main/experience/index.js)index.js file. We bring together the schema and the resolvers to configure the Apollo Server. Additionally, the resolvers need access to instances of the data sources. This is accomplished using the Apollo server *context function*, which is provided as an argument to the `startStandaloneServer` function.

[index.js](https://github.com/Kong/KongAir/blob/main/experience/index.js)index.js

...
const typeDefs = require('./schema');
const resolvers = require('./resolvers');
...
async function startApolloServer() {
  const server = new ApolloServer({ typeDefs, resolvers });

  const { url } = await startStandaloneServer(server, {
    context: async ( { req } ) => {
      const { cache } = server;
      return {
        dataSources: {
          customerAPI: new CustomerAPI( req, { cache } ),
          bookingsAPI: new BookingsAPI( req, { cache } ),
          routesAPI: new RoutesAPI( { cache } ),
          flightsAPI: new FlightsAPI( { cache } ),
        },
      };
    },
  });

  console.log(`
    🚀  Server is running
    📭  Query at ${url}
  `);
}

startApolloServer();

The context function is executed for every incoming GraphQL request, and within this function we define new data source instances. In the cases of the CustomerAPI and BookingsAPI, we also pass in the incoming request object which allows the data sources to forward authorization headers to the upstream API calls.

### Run and query the experience API

We've covered the basics of the experience API design. Let's run the GraphQL service and see it in action.

The server is a NodeJS application and requires `node` and `npm` to be installed and available in the path prior to running. The service has been tested with Node version `17.9.1` and npm version `8.11.0`. You will also require `git` to obtain the source code in the instructions below.

From the terminal, clone the KongAir repository and change into the `experience` directory:

git clone https://github.com/Kong/KongAir.git && \
  cd KongAir/experience

You may have noticed above that the data source base URLs are configured using the [dotenv](https://www.npmjs.com/package/dotenv)dotenv configuration library. The KongAir repository provides a default `.env` file that configures the base URLs to point to the hosted `api.kong-air.com` services. This will allow the GraphQL service to run and route requests to the hosted APIs without running the domain services yourself. Alternatively, you can run each of the domain API services locally following the instructions in the [experience API documentation](https://github.com/Kong/KongAir/blob/main/experience/README.md)experience API documentation.

To continue, run the Apollo server:

npm run start

The running server reports it's listening endpoint:

> kong-air-experience@0.1.0 start
> node index.js

🚀  Server is running
📭  Query at http://localhost:4000/

Before running GraphQL queries against the server, we have to understand the method the KongAir system uses to verify user identity.

JWTs provide an easy way to transfer identity between services. The domain REST APIs require a JWT with a payload that contains a `username` field which is used to identify API users.

All KongAir services require the JWT to be provided in the request Authorization header as a [bearer token](https://datatracker.ietf.org/doc/html/rfc6750)bearer token. Here is an example header with a bearer token:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIxa1ZYWUw1TmFybHRZM3F6dE9QejFQaGFWbXlZaUtjdCIsInVzZXJuYW1lIjoiZGZyZWVzZSJ9.5uJsT130YD_RJlf0kW_l3YbXnUh6H-HmSX37n1H6N08

The KongAir repository provides a helper file ([JWT.env](https://github.com/Kong/KongAir/blob/main/JWTs.env)JWT.env) with some valid example JWTs that you can use to make queries to the experience API.

From the `experience` folder, source in the `JWT.env` file which loads the variables into your environment:

source ../JWTs.env

Now we can query the GraphQL API with `curl`, providing a query string as well as the user’s JWT in the request:

curl -s -XPOST \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $DFREESE" http://localhost:4000 \
  --data '{ "query": "{ me { name username } }" }'

And the server will respond with the user's information:

{"data":{"me":{"name":"Danny Freese","username":"dfreese"}}}

You may wonder why the GraphQL query is sent as a `POST` request. GraphQL query expressions can be complicated nested JSON objects, and it may be simplest to pass them to the server as a JSON formatted body in an HTTP request. Idiomatically, GET requests do not support a request body, so POST is commonly used. However, GraphQL servers should also support accepting a query in a GET request via the query parameter. Here is the same example via GET:

 curl -G -XGET http://localhost:4000/ \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $DFREESE" --data-urlencode "query={me{name username}}"

From the perspective of the client, what exactly makes the GraphQL API different from the upstream domain REST APIs? The dynamic nature of the GraphQL query capabilities puts more power in the hands of the client making requests. Imagine KongAir is building a mobile application with a screen that shows the user their personal information including their username, address, and frequent flier number. The following client query provides this information:

curl -s -X POST \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $DFREESE" http://localhost:4000 \
  --data '{ "query": "{ me { username information { address frequent_flier_number } } }" }'

And the server responds with these specific fields:

{"data":{"me":{"username":"dfreese","information":{"address":"567 Street St","frequent_flier_number":"FF987abc"}}}}

The same application has a different screen that shows the user their current bookings. This requires a different upstream domain API, but the GraphQL service can compose it together with the customer information for us. We don't have to create a new BFF API; we just construct a different query on the client side. Here is an example request for the user's bookings:

curl -s -X POST \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $DFREESE" http://localhost:4000 \
  --data '{ "query": "{ me { username bookings { ticket_number seat flight { number route { origin destination } } } } }" }'

And the user's bookings are returned:

{"data":{"me":{"username":"dfreese","bookings":[{"ticket_number":"RIN74XEJWG","seat":"18A","flight":{"number":"KA0288","route":{"origin":"LHR","destination":"BOM"}}},{"ticket_number":"RDAWJ63VAP","seat":"19C","flight":{"number":"KA0289","route":{"origin":"LHR","destination":"HND"}}}]}}}

## Designing GraphQL Queries with the Apollo Sandbox

In development mode, the Apollo SDK provides an embedded GraphQL IDE called the [Apollo Sandbox](https://www.apollographql.com/docs/graphos/explorer/sandbox/)Apollo Sandbox. To use the sandbox with the server running, open your browser to [http://localhost:4000](http://localhost:4000)http://localhost:4000 and you should see an interactive interface to build GraphQL queries.

You may find this easier to use than a command line for exploring the capabilities of the GraphQL service. To successfully make requests to the KongAir API, you will need to configure the Sandbox with the bearer tokens. Open the IDE Settings, then Connection Settings and provide the token information in the Shared headers section.

### Summary

GraphQL offers a compelling solution for building dynamic APIs and is particularly useful for clients that present data to end users. These types of experience APIs are beneficial to clients that need to avoid the rigidity of traditional REST-based APIs and GraphQL provides a key abstraction layer towards that goal.

But once you've integrated GraphQL into your API ecosystem, the job isn't complete. GraphQL APIs need management, as all API technologies do. Protecting the API is paramount as you expose it to end-user applications and the full outside world.

In the next entry of our series, we'll look at using [Kong Konnect](https://konghq.com/products/kong-konnect)Kong Konnect with [Kong Gateway](https://docs.konghq.com/gateway/latest/kong-enterprise/)Kong Gateway to apply critical governance to our KongAir experience API using a declarative and modern approach (aka [APIOps](https://konghq.com/blog/tag/apiops)APIOps). See you there!

**Topics**
- [GraphQL](/blog/tag/graphql)GraphQL- [API Design](/blog/tag/api-design)API Design- [API Development](/blog/tag/api-development)API Development
Rick Spurgeon
Product Engineer, Kong

Recommended posts

## Ready to see Kong in action?

Get a personalized walkthrough of Kong's platform tailored to your architecture, use cases, and scale requirements.

[Get a Demo](/contact-sales)Get a Demo