DEV Community: Sandip Devarkonda

From Basics to Supergraph: A practical guide for your GraphQL adoption journey

Sandip Devarkonda — Tue, 30 Apr 2024 07:04:06 +0000

When implemented effectively, the evolution of GraphQL within an organization often transitions from a singular graph, or subgraph, to an expansive network of interconnected graphs, known as a supergraph, through the process of GraphQL federation. This progression, however, is not mandatory for entities managing a single or a few domain databases. When such expansion does occur, it usually unfolds in a cyclical manner, with the continuous development of new subgraphs. Key insights gained from the construction of a supergraph are invaluable, feeding back into the refinement and enhancement of subgraph capabilities. Concurrently, the tools and technologies supporting both subgraphs and supergraphs are advancing, propelled by these accumulated learnings, marking a new phase in the GraphQL lifecycle.

All models are wrong, but some are useful. This model aims to be useful to GraphQL practitioners or to anyone curious about GraphQL (GraphQurious?) by enabling them to anticipate the challenges of later/upcoming stages and use insights from others’ experience to fine-tune their current efforts and be better prepared.

Glossary

Subgraph: A GraphQL API that’s one of the components in a larger graph. In more practical terms, it’s the GraphQL equivalent of a microservice – typically this is a GraphQL API built and operated by a single team that owns a domain.
GraphQL federation: a term introduced by Apollo to describe the process of combining multiple subgraphs into a unified GraphQL API/schema (with relationships between subgraphs).
Federated GraphQL API: Output of the GraphQL federation process, typically used in the context of using Apollo tooling. Other GraphQL projects also sometimes use this term.
Supergraph: A generic term used to describe afederated GraphQL API. The graph in supergraph refers to the combination of API domains rather than just the API itself.

Caveats

Iterations and nonlinearity: Adoption journeys are not as linear. Most organizations will go through multiple iterations of building GraphQL APIs/layers. So it’s possible, for example, to go from stage 4 to stage 1 as you pick up the task of building a new subgraph.
Org structure and multiple stages: More than 1 independent or dependent GraphQL journey could play out in an organization, sometimes on the same team. So it’s possible to belong to different stages at the same time.
Measure of complexity, not competence: It’s quite normal to not need anything more than a single simple GraphQL API on a domain database and stay in stage 1 for years. A position in the maturity model is more indicative of the data access patterns that need to be supported and less about the ability of teams to support more elaborate patterns.

We are now ready to dive head-first into this framework. Our example is an e-commerce application:

**1. Teams/people: **The application is being built by a hypothetical engineering function with multiple domain teams.

2. Application: The following wireframes for this app will help us navigate through the stages of this framework,

GraphQL maturity model

The GraphQL maturity model plots the evolution of subgraphs and their interplay along two axes: the value of the GraphQL solution and the number of teams or subgraphs involved in the solution.

The model plots the natural evolution of a graph in an organization with multiple domains. It also calls out the key focus areas in each of the stages in the model as they change from a single team’s concern to potentially affecting the entire engineering organization. At each stage, sample queries demonstrate the art of possible enabled by the API. This reflects the growing complexity and maturity of the federated GraphQL API itself.

Stage 0: GraphQL curiosity
Welcome! If you’re curious about GraphQL and its ability to solve engineering challenges in the world of APIs, you’re in the right place.

GraphQL emerged from very real-world use cases at Facebook. There are significant parallels between Facebook in 2014 and enterprise organizations – a large number of engineering teams, lots of data, and the need for seamless inter-team collaboration.

Stage 1: Building a subgraph
Building and deploying a production-ready GraphQL API is a crucial first step.

Most GraphQL literature emphasizes the later stages of this maturity curve – about how to value compounds when you “join” more than two subgraphs – and that’s mostly true. But this stage is the rate-limiting factor – if you can’t build production-grade high-quality subgraphs quickly enough, you won’t have that shiny unified API layer anytime soon.

Speed is of the essence here and the associated trade-offs you make in this stage might make the difference between having a practical API layer in production vs. a paper tiger that’s more design than code! It’s harder to build production-grade subgraphs than to join two or more subgraphs – a problem that can be solved with the right tooling.

At the end of this stage:
Our architecture looks like this:

Note: This diagram is reductive by design. Your first domain GraphQL API can also be a part of an overarching program in your organization like technology modernization

The Catalog subgraph serves the following schema:

catalog_products {
id
name
description
}

Implementation patterns
The GraphQL ecosystem has evolved to produce a variety of subgraph authoring tools and approaches. Key among these are schema-first, code-first, and domain-driven approaches. As your graph matures, you’ll likely use more than one approach depending on the specific use-case. We have written extensively about subgraph tooling here.

Lessons from building a supergraph can be applied to how subgraphs should be built. Revisit this section after the end of this post and see if that changes your opinion of what subgraph quality really means.

GraphQL API management tools
Depending on deadlines and how experimentative your efforts so far have been, you might want to deploy your subgraph in production for client applications to start consuming this wonderful API. If this is your first GraphQL API, you’ll need to factor in some non-functional concerns like observability, performance, and security. Some subgraph tools offer such capabilities out of the box.

In the future, if your graph evolves to contain more than one subgraph, you may have to revisit your architecture to see if these concerns are better off being addressed in a centralized way.

Stage 2: Building multiple subgraphs
At the end of stage 1, you’d have validated your choice to introduce GraphQL into your stack and your implementation choices. Now, inspired by the success of this effort, your own team or another one could choose to build another subgraph (this can also be via another data source in the domain from the first example). You can choose to reuse the same tooling from stage 1 or go in a different direction to continue learning or to use the best tools for this new data source.

The two subgraphs are not related yet. They represent independent work streams that are not affected by each other.

Note: the difference in GraphQL subgraph design reflects the diversity of implementation patterns in the GraphQL ecosystem.

The new fulfillment subgraph serves the following schema:

Order{
id
value
Products: [Product]
}

Product {
id
qty
}

Before beginning this stage, check if you need to reevaluate the tooling based on your experience in stage 1. A big benefit of GraphQL is ecosystem interoperability is that you can use the right tooling for the use case at hand, as long as you build a GraphQL-spec compatible API.

*Stage 3: Schema stitching *
We have reached the aforementioned point of necessary collaboration. It’s the first stage where the sub in subgraphs makes sense – each of the domain graphs from the previous two stages become a part of a unified schema.

It’s natural to want to query the two independent subgraphs in the same query/request and present a unified schema to API consumers. For the consumer application or service, it’s objectively simpler to do so instead of making two different requests. The developer experience of working with one unified schema is also far superior.

Schema stitching offers a way for completely independent subgraphs to be “unified.” This “union” of types is typically done using some kind of a gateway. In our e-commerce example, schema stitching allows you to query the entirety of the following schema in one request:

catalog_products {
id
name
description
}

Order{
id
value
Products: [Product]
}

Product {
id
qty
}

💡Tip
Schema stitching as a concept and product capability has evolved into more than just a union of types since it was first introduced. You can build a custom tool or script to do this yourself or use a third-party GraphQL gateway tool to route requests to the right subgraph. Some of these products allow you to merge (conflicting) types across subgraphs by allowing you to define the logic to do so.

Schema stitching is the first step of the next stage as well. Choosing when to move to the next step is best captured by this comment on Reddit:

“Most of the advantages of GraphQL Federation occur when there are clear administrative boundaries between the data sources (Conway's law). That doesn't happen until larger team sizes, so IMO GraphQL Federation seemed like unnecessary complexity at this stage.”

💡Tip
Schema stitching solves the problem of a unified GraphQL schema fairly elegantly without a lot of effort. Depending on your choice of tools, you may have to either use some form or namespacing-based aliasing or provide conflict resolution rules to merge types.

Stage 4: GraphQL composition or federation
Federation. Remote schemas. Distributed schemas. These are some of the names given to this stage by various tools in the GraphQL ecosystem. The defining trait of this stage is that types across subgraphs can have hierarchical relationships to each other.

Back to our example to illustrate this. The third wireframe in our original set of requirements needs data from both the subgraphs – a specific order and information about associated products. This data is relational in nature – there’s a 1:many relationship between an order and products. We need to execute a nested query on our composed API. This can be done by defining a relationship between the order type and the catalog_product types by using the common fields id.

We still need a centralized gateway to front this related, united schema. This gateway, like the one used for schema stitching, routes part of the requests to the right subgraph. With the right kind of subgraphs (ones that allow batching), most gateways can also optimize performance by making two requests in total, one to each subgraph instead of making N + 1 requests.

The GraphQL Foundation has created a working group to formally define a formal specification for composition.

💡Tips
API platform benefits
Composability is where the value from GraphQL starts to compound with every product iteration. The richness of your unified graph can be defined as its ability to allow “joins” between its constituent subgraphs. The easier it is to do this, the easier it is to build seamless user experiences across previously siloed data in the org. This is the holy grail of any API platform strategy out there.

People and processes
With more “coupling” in this stage, the challenge of federated ownership of the unified GraphQL schema is more critical to solve. Enabling multiple teams to collaborate on and fearlessly evolve the unified graph API, without conflicts, is key to building high-quality applications. You can do this by using tools like schema registries that support schema integrity tests and regression tests (on production traffic preferably). This is another form of the classic microservices integration problem which can be solved with good tooling that provides early warning (the earlier the better – pre-commit is best!).

Performance concerns

Observe the number of redirections and layers at play here. If your gateway and subgraphs aren’t performant, your composed API won’t be performant as well.
Your subgraphs need to support batching/filtering for types involved in a join as a child. In our example, if the catalog subgraph didn’t have support for a query such as the following, you can’t reduce N + 1 requests to 2, which will result in abysmal performance:

query filterProducts {
  product(where: {id: {_in: [<list of products from order>]}}) {
    id
    name
  }
}

Stage 5: What’s next
After coming up with the periodic table in 1869, Mendeleev could see some patterns in the framework well enough to accurately predict as-yet-undiscovered elements. In a similar vein, what patterns can you see in the above model?

A couple of observations stand out:

Subgraphs are key: Good subgraphs make good GraphQL APIs. As we can see above, if your subgraphs are not rich (support filtering, sorting, batching/composition, etc.), your unified GraphQL API isn’t going to be very useful either. However, it is very hard to:

Manually add aggregations/compositions capabilities to a subgraph.
Manage upstream API and data sources.

Another way to state this problem is this: How do you build subgraphs that allow this kind of composition i.e. allow you to filter a parent object by its child’s attribute?

# fetch parent by child's attributes
query filterOrder {
  order(where: {order.product.description {_contains: "discount"}}) {
    id
    value
    products {
    id
    description
  }
}

Hint: unless you work some magic into the subgraph, you cannot do this without having to create a separate subgraph. Powerful queries like this are needed to deliver on the promise of GraphQL Federation.

More complexity needs more communication: As your GraphQL API evolves to incorporate more teams/subgraphs, inter-team collaboration becomes more valuable than productivity gains. As any good engineering exec will tell you, this is true of any growing team/org.
Single point of failure: Composition/federation is an attempt to centralize subgraphs (microservices). Centralized entities are lightning rods for failures with unknown root causes. How do you instrument this architecture for preventing this i.e. keeping MTTR as low as possible? Think “git blame” for logs.
Performance: GraphQL platforms, like any API platform - all of them distributed systems, are susceptible to performance issues when federating over multiple independent domains. How do you instrument a platform in a way that guarantees the best possible performance agnostic of the underlying domain i.e. what’s the platform latency of your system (over and above your domain’s own query latency).
Decoupling the graph from GraphQL: An innocuous-looking learning from stage 1, which holds true later as well, is that API consumers may not always be ready to invest in learning a new specification like GraphQL. Also, what if frontend tooling evolves to be more receptive to gRPC?

The next logical step in a mature GraphQL API will be to find a way to address federation/composition concerns from the get-go without compromising productivity. Supergraph.io is an architecture framework that formalizes principles that allow you to address these concerns.

Why Platform Engineering 2.0 Needs Compiler-Style APIs and Edge Computing

Sandip Devarkonda — Fri, 29 Mar 2024 04:38:54 +0000

Introduction

Platform engineering has become very popular within the developer ecosystem, especially in mid to large engineering teams. It is transforming how software is built and deployed. By centralizing infrastructure and tools, platform engineering has enabled developers to focus more on coding and less on managing underlying operational complexities.

This shift has significantly boosted developer productivity and enhanced Developer Experience (DX). For instance, tools like Docker, Kubernetes, etc., provide a standardized way to deploy and manage containerized applications, which can and has been instrumented to work automatically, sometimes not even requiring a click of a button!

DevOps principles inspired platform engineering. Consequently, there’s a lot of emphasis on the “operational” aspects of the software development lifecycle, like self-serve infra, automated deployments, monitoring, etc. A simple search for the term “platform engineering” further illustrates this point when you see the kind of developer/infra tooling organizations that participate in the discourse around this concept.

However, there’s a massive opportunity to further realize the goals of platform engineering by applying the same underlying principles to the coding aspects of application development. For example, you might say, now that we’ve made this app hyper-efficient for new code or service to be packaged and deployed to production from the moment it appears (say in a specific git branch), how about making it equally seamless to generate the service/code?

This isn’t a radically new idea – however, this particular optimization is the last big remaining hurdle in getting new ideas/iterations from conception into production faster.

The CNCF whitepaper on platform engineering already recommends measuring the efficacy of a platform by measuring indicators such as the following:

Organizational efficiency: efficiency of a platform in reducing common work like the “latency to build and deploy a brand new service into production.”
Product and feature delivery: DORA metrics, which include “Deployment Frequency,” which also implies “iterate/build frequently.”

So, how does one enable an application developer to build quickly and often as a platform capability? By first identifying the undifferentiated aspects of building APIs.

Build CRUD APIs with compiler middleware: Data-APIs-as-code

Over the years, many developers have been wise to the pattern that 60-70% of any service/API is boilerplate CRUD code that does nothing but I/O on an underlying data source (database, existing APIs, 3rd party APIs, etc.).

Paraphrasing a recent quote from Stephen Wolfram: _“A lot of what they [developers] do is write slabs of boilerplate code… with a high enough level language, that slab of code turns into one function that you can just use… that sort of boilerplate programming is going the way of Assembly Language.” _

Several developer teams and open source tools are trying to reduce such boilerplate code by building a general-purpose middleware that can translate a CRUD API request into a “query” that is understood by the underlying source like SQL.

This compiler (or transpiler, if you will) approach works best when said APIs are autogenerated from the underlying source schema, providing the compiler with a source and target representation of data.

In other words:

1) convert metadata or config, such as the following, into fully functional CRUD APIs:

{ “source”: { “type”: “Postgres”, "tables": ["authors", "articles", …], "one-to-one-relationships": [{articles.author_id, author.id},..], "one-to-many-relationships": [{author.id, articles.author_id},..], } }

2) Convert a request like https://yourdomain.com/rest/authors-and-their-articles into SQL like:

Select author.* and article.* from author left join articles on author.id =article.author_id

The above example might seem trivial, but this approach scales to complex scenarios like having multiple data sources with related types. Let's say the “articles” table in the above example is sourced from a separate MongoDB instance. It’s possible to specify the semantics of querying across disparate data sources in a composable manner, one that generates a rich data graph that can be used to build powerful features (while also solving for issues like N+1 querying, performance/scalability, etc.).

Specifications like GraphQL, OpenAPI, ODATA, etc., enable even better standardization on the output formats, making it easier for frontend developers to consume this data/APIs. The centrality of types in these specifications also lends itself to automatic documentation and interactive sandboxes for the API consumer.

Too often, we speak of documentation and onboarding in the context of the backend developer, but imagine the possibilities when even a new frontend developer is presented with a data or API catalog and a sandbox to build their new features.

The rise of low/no-code platforms is a testament to this trend. Such tools were typically leveraged for internal or low-priority applications, but the same principles and tools are being leveraged in mission-critical projects where speed is of the essence by startups and enterprises alike.

Build and deploy CRUD APIs: Data-delivery-as-code

To the astute observer, it should be apparent that the compiler middleware from the previous section can be built to be stateless.

This opens up some interesting opportunities to deploy this “function”:

Middleware can be deployed at the edge, as close as possible to the end users of the API/service.
The data-source-to-API metadata can also be extended to specify the data's target edge location requirement, while the complexities of the CI/CD pipeline that deploys this data can be abstracted away.

In short, it’s possible to declaratively specify details for a data source (like db, replicas, caching requirements, etc.), build APIs on it, and deploy APIs to your choice of data centers or edge location by just writing up some metadata or config like this:

{ “source”: { “type”: “Postgres”, "tables": ["authors", "articles", …], … "api_regions": ["US-West", "US-East", …], "db_replica_regions": ["US-West", "EU-East", …], "caching_regions": ["EU-East", …], … } }

This kind of platform capability is incredibly powerful. But it shouldn’t be too hard to imagine that learnings from the current state of platform engineering, like infrastructure-as-code, are being extended to data and APIs.

Conclusion

The focus of platform engineering is shifting to the next logical step in the journey to improve developer productivity and experience, specifically for the application developer.

As dictated by the first principles of platform engineering, the repetitive operational part of writing code for services/APIs on data has been identified. Agile teams are now offering these operations as new automated capabilities in the platform. Their application developers are now enabled to go all the way from data sources to the date delivery destinations at the edge with just a few lines of configuration, allowing them to focus on product features that delight their users.

It’s a great time to build applications in the modern enterprise!