 |
VOOZH | about |
|
VOOZH | about |
We’re so glad you’re here. You can expect all the best TNS content to arrive Monday through Friday to keep you on top of the news and at the top of your game.
Check your inbox for a confirmation email where you can adjust your preferences and even join additional groups.
Follow TNS on your favorite social media networks.
Become a TNS follower on LinkedIn.
Check out the latest featured and trending stories while you wait for your first TNS newsletter.
In the previous post in this series, we discussed the complexities of building and consuming APIs in enterprise data landscapes. These environments involve multiple data domains managed by different teams and numerous applications, leading to challenges due to constrained resources and conflicting goals.
The Supergraph Architecture Framework (SAF), developed from our experience with federated data access and GraphQL federation, addresses these challenges by proposing strategies for constructing domain APIs (subgraphs) and data access API platforms (supergraphs).
This framework offers an operating model for team collaboration, acting as an API marketplace with API producers and consumers. It facilitates onboarding API producers, provides high-quality supergraph APIs for consumers and emphasizes high-quality domain APIs with capabilities like filtering, sorting and pagination.
The SAF lays the foundation for an operating model and system design that enable federated domain ownership. In enterprise data and API landscapes, this helps address challenges with federated data access and makes use cases like API orchestration and API composition easier to tackle.
API orchestration involves managing multiple API calls and sequencing the requests and results to perform a complex task or workflow. In our reference context, an example of API orchestration might involve the following sequence:
The orchestration layer handles these steps in sequence, ensuring each step completes successfully before moving to the next, and combines their responses into a single, cohesive outcome for the user.
👁 Diagram of supergraph restaurant-delivery example.
Orchestration is largely driven by the API consumers based on end user requirements. It is challenging, as it typically spans multiple domains. Orchestration using traditional methods requires the same type of “glue” code/endpoints that aggregation does — only in this case, that glue is more complex, as we can see from our example. Orchestration also usually involves multiple mutations, which further compounds the challenge.
Once again, we’ve run into the challenge of ownership: Should the consumer team own orchestration code? Does that team have the necessary skills to build performant orchestration endpoints? These are all operational challenges that need to be addressed to build a powerful orchestration layer on top of domain APIs/data.
A good API platform must provide the semantics for definition of complex workflows that may be interspersed with business logic functions. Similar to the way supergraph architecture allows for relationships between domain CRUD APIs and business logic, the response of API calls can be chained to functions that can act independently (or even call other CRUD APIs from the supergraph) or vice versa.
The substrate for this capability is made possible by the fact that every piece of data from any source (databases, APIs, etc.) and types in business logic code are standardized on the supergraph’s semantic layer. This enables a supergraph to provide the semantics for developers, including API consumers, to articulate a workflow using just declarative configuration.
Integrations with third-party orchestration software like Camunda, Orkus, Temporal, etc., make this experience even more seamless for developers. Read more about API orchestration.
| Problem | Solution |
| New workflows need new orchestration endpoints. | Supergraph requires that API consumers have the ability to self-serve demand for new workflows using declarative config. |
| Authoring workflows requires knowledge of backend systems engineering. | Supergraph configuration is declarative, which democratizes the ability to engineer scalable workflows. |
API composition, which can be thought of as a special case (or evolution) of API integration and orchestration, refers to the technique of combining multiple API responses into a single unified response with hierarchical information from the different calls. Put another way, composition fetches related data from disparate sources in a cohesive way — so, aggregation and orchestration for a read operation. An example of API composition would be the following data for a user of our food delivery application:
Getting this information involves making a request to three different domains in a sequence, at each step using the response from the previous, and finally combining the overall result set into a single hierarchical response that represents the relationship between the three entities (orders, restaurants and payments).
Supergraph(QL) architecture advocates for awareness of the underlying sources or domain and standardization across a set of a heterogeneous set of sources. This allows a supergraph to provide a self-service model for API composition, without requiring any custom development, by making available the following two capabilities:
| Problem | Solution |
| Every data composition permutation needs an composition endpoint. | A supergraph automates composition with declarative relationship definitions between data across sources. If the relationships from the same source can be inferred programmatically, the supergraph can automate this. |
| Authoring workflows requires knowledge of backend systems engineering. | Supergraph configuration is declarative, which democratizes the ability to engineer scalable workflows. |
Read more about API composition.
Building on the work from the previous post on the Supergraph Architecture Framework, we can compile the following comprehensive checklist for any API platform (referred to as a supergraph) design that seeks to address the challenges of API integration, aggregation, composition and orchestration.
| Guideline | Description |
| 1. Integration | Making it easy for API consumers to integrate APIs into their services |
| 1.1 Multiple API formats | Can the supergraph platform automatically provide output formats beyond GraphQL such as REST/OpenAPI? This is required to support the integration needs of multiple consumers. |
| 1.2 Documentation | Does the supergraph platform help domain or platform owners maintain API documentation? If the underlying domains (database, code or APIs) are already documented, are those automatically picked up by the supergraph platform? |
| 1.3 Standardization | Does the supergraph platform provide or enforce a standardized domain API design (pagination, filtering, sorting, etc.)? |
| 2. Aggregation | Making it easy for API consumers to aggregate/batch multiple API calls into one |
| 2.1 Relationships | Does the supergraph provide a way of creating relationships between any two entities or endpoints without requiring changes from the domain owners? |
| 2.2 Composability | How many “join” features does the supergraph provide, given a relationship between two entities in the supergraph? |
| 3. Orchestration | Making it easy for supergraph stakeholders to author custom API orchestration |
| 3.1 Federated mutations / decoupled orchestration business logic | Does the supergraph provide a way to author orchestration flows within or across underlying domains? |
Measuring the effectiveness of a platform’s design to meet this criteria and the time and effort investment required to build these capabilities will provide any architect with a clear indication of the likely success of their platform initiative.
