Shandor Sharvari

Posted on Oct 9 • Originally published at shandor-sharvari.Medium

API-Led Connectivity - Practical Questions Answered

#architecture #api #designpatterns #softwareengineering

Part 1 - From Concepts to Foundations

API-Led Connectivity is a simple but powerful way to build things. This architectural pattern defines a layered structure with clear responsibilities for each layer and well-defined connections between them. There are three types of APIs — System, Process, and Experience — which handle data, business logic, and representation, respectively. The pattern also defines the order and flow of API calls. Not only does it help you separate data, representation, and business logic at the solution level, but it also enables you to reuse APIs in various ways across different systems and scenarios.

Many articles and blogs discuss the benefits of this popular pattern. But the real challenge begins when you start implementing it. This article is inspired by the fact that teams tend to ask the same questions again and again when they begin development.

When providing answers, it’s critical to consider that every decision involves trade-offs between business needs, technological capabilities, budget, and delivery time. Each design principle and pattern comes with strengths and limitations. The real challenge is determining whether the chosen solution resolves more issues than it creates. So, while a certain approach might seem like the obvious choice at first glance, there are always exceptions — scenarios where its principles may need to be bent, or even broken.

The article examines API-Led Connectivity from that perspective, aiming to answer common practical questions.

It turns out there’s more to unpack than expected, so let’s split it up into parts.
In Part 1, we’ll talk about the basics of API-Led Connectivity and look at when and where it makes sense to use it, taking into account its advantages and drawbacks.
In Parts 2 and 3, we’ll cover the questions that teams often ask when they start using API-Led Connectivity.

1. Why Do We Need Yet Another Pattern?

This question is often asked even before the definition of the pattern is given. So, let's start by answering it first, and then provide a detailed explanation afterward.

API-Led Connectivity makes it easy to create modular APIs. The best part is that you can connect these APIs in many different ways to work with a lot of different systems, and you don't have to rewrite any code to do it. This pattern solves some common problems in system design and development by putting APIs into reusable parts:

Reusability: Modular APIs can be recombined across different projects and avoid doing the same work twice.
Clear separation of concerns: By splitting data access, business logic, and representation into separate layers, the structure is cleaner.
Loose Coupling: By aligning APIs with specific roles and communication boundaries, inter-service dependencies are kept to a minimum. This lets each component change and scale independently.
Abstracted business logic: Business logic doesn’t depend on the data structure or consumers. It allows for the development of clean, focused and reusable algorithms.
Role-based system design: APIs are structured based on what they do, which makes systems modular, easy to understand and maintain.
Scalability: Individual components can scale independently without affecting the whole system.
Faster development: Teams can deliver faster because they don't have to start from scratch with reusable APIs.
Parallel teamwork: Different teams can work on different parts of the system at the same time, which speeds up delivery.
Simplified maintenance: A clean structure means fewer bugs and smoother updates.
Cost-efficiency: Less duplicated effort means lower development costs.

Therefore, if you want to create systems that are fast to develop, easy to scale and maintain, API-Led Connectivity might be helpful for you.

2. How Does API-Led Connectivity Work?

API-Led Connectivity introduces a layered approach with three types of APIs, each with a different purpose and clear connections between them:

System API hides the specific technology and structure of a data source from the rest of the system. It presents data as reusable models. The data source, usually called System of Record (SoR), is typically a database, but it can also be a third-party enterprise platform or another system.
Process API wraps up essential business logic. It is decoupled from both data sources and consumers. Instead, it relies on models that are shared across API layers.
Experience API combines and formats these models into representations that meet the needs of a specific consumer, typically a user interface such as web pages or mobile applications.

System and Process APIs are usually created for internal use and are meant to be reused. They stay hidden from external systems and focus on modularity.
Experience APIs, on the other hand, are designed for UI or integration with third-party systems. They adapt representations to fit the needs of each consumer. Experience APIs can be public and accessible from the internet.

The API flow usually goes like this:

Consumer ➜ Experience API ➜ Process API ➜ System API ➜ System of Record

But the Process API can be skipped if all you need to do is combine and map data, which means you don't need business logic:

Consumer ➜ Experience API ➜ System API ➜ System of Record

API-Led Connectivity outlines some important relationships and design principles:

Each System API connects with just a single data source. But several System APIs may link up with the same source.
Process APIs can call multiple System APIs and even other Process APIs.
Experience APIs usually call Process APIs, but they can also call System APIs directly. But, they shouldn’t call other Experience APIs. Most of the time, each Experience API is designed for a certain consumer. But sometimes one API can work with more than one app. For example, both iOS and Android mobile apps can use a unified representation.

The pattern’s structure is usually shown in a simple way:

You can think of API-Led Connectivity as similar to the MVC pattern, but applied at the solution level:

System APIs work similarly to Models. They handle the raw data.
Process APIs serve as Controllers. They are where all the business logic takes place.
Experience APIs are like Views. They shape and present that data in a way that is applicable to the consumer. This handy comparison makes it clear what each API layer does.

But in real life, things can get more complicated. Data often comes from more than one System API, and the business logic may cover several Process APIs. It’s common to see multiple consumers, each one served by its own Experience API. That’s why, even though it looks simple at first glance, real-world applications can get very complicated. Data is dispersed across several SoRs, each served by its own System APIs. Process APIs usually call multiple System APIs and sometimes other Process APIs. Various consumers, such as web and mobile apps, require more than one Experience API, which represents data coming from a number of Process APIs and, in some cases, directly from System APIs.

That’s why API-Led Connectivity pairs well with Domain-Driven Development. Each API is implemented within a bounded context, and data is sent between them using domain models.

3. Example: An Online Retail System

Think about a large online shopping site that offers a broad range of features for both customers and sellers, such as product catalog and comparison, wish lists, full-cycle order processing, marketing campaigns, inventory and customer management, and so on. Like any modern online store, it’s represented not only by a website but also by mobile apps for all popular platforms. Under the hood, the data is spread across multiple SoRs, including databases, CRM, ERP, and others.

API-Led Connectivity aligns well with large, multifunctional systems like this, providing a scalable and modular solution with reusable components:

Many System APIs, each communicating with a single SoR, such as product catalog, inventory, user data, and so on.
Several System APIs connect to the same multipurpose SoR, like CRM and ERP, separating their data in a more granular way providing better reusability and scalability.
Process APIs aggregate and process data from multiple System APIs.
Different Process APIs can use the same System API, leveraging its data in different contexts. For example, pricing data is needed for both the Product Catalog and Orders Processing.
Some Process APIs call other Process APIs - sometimes without retrieving data from System APIs - allowing for more complicated business logic.
Experience APIs serve both web and mobile platforms. The web app has its own dedicated Experience API, while both iOS and Android apps share one to ensure a similar user experience on both platforms.

This example demonstrates how API-Led Connectivity makes it possible to build a solution in which components are widely reused, reducing development time, simplifying the maintenance of each one, while also allowing each component to be scaled independently of the others.
For instance, the Pricing System API is used by both the Order Processing and Product Catalog Process APIs, and the Product Catalog Process API is called not only by both Experience APIs, but also by the Product Comparison and Marketing Process APIs.
Speaking of scalability, during Black Friday season, components like Product Catalog, Order Processing, Cart, Wishlists, Inventory, and others must be upscaled, while Articles, Marketing, and Suppliers can remain at their usual level.

4. When Should We Use API-Led Connectivity?

API-Led Connectivity is good for systems that require clean architecture and clear communication patterns due to their complexity and scale. Here are some suitable scenarios:

Complex systems with many APIs or microservices, such as large enterprise projects with intricate interaction flows.
Integration of multiple data sources or third-party systems to make a consistent and structured format.
Platforms or ecosystems that offer a wide range of services, such as cloud providers or enterprise systems.
Need for independent scaling of each part of the system to get the best performance and lowest cost.
Development is spread out over several teams, so it needs to be modular and have clear boundaries so that they can work on it at the same time.

5. When Might API-Led Connectivity Not Be Worth It?

API-Led Connectivity has a lot of benefits, but it also has some drawbacks, most of which are due to its layered nature:

Layered overhead: Each new layer adds more components that need to be designed, deployed, and maintained. That can slow things down and give development and operations teams more work, especially at first.
Latency stack-up: Every layer adds another step to the data flow. If not carefully optimized, this can slow down response times and decrease performance, especially for high-throughput or real-time services.
Propagation of changes: Some updates, like adding new features to a product, may require changes or retesting at multiple levels, which can make rollouts and versioning more difficult.
Cross-layer coordination: Teams need to work together closely across API layers to make sure everything stays in sync. Without clear boundaries and ownership, you could run into problems like bottlenecks or inconsistent implementations.
Debugging complexity across layers: It is harder to fix problems when they span many layers. To find a bug, developers might have to follow the whole chain.
Redundant logic risks: If the lower layers aren’t well-defined, higher layers might reimplement similar business logic again, which goes against the goal of abstraction and reuse.
Costly setup and planning: Making modular and reusable APIs takes time and effort up front. If you're in a hurry to deliver something, this structured approach can feel like extra work.
Harder onboarding for new teams: It takes time to understand how all the layers fit together. Without solid documentation and guidance, new teams might have difficulty learning the whole flow.

Considering that, the pattern might not be the best option in every case. Here are some situations where the pattern might seem like overkill:

Small and simple projects: A lightweight architecture is faster to build and easier to manage.
Short-lived projects or MVPs: When delivery speed is more important than scalability or modularity.
Single or small teams: Designing and keeping up with multiple API layers might slow things down instead of speeding them up.
Performance-critical systems: When getting ultra-low latency is essential, since every API layer adds HTTP overhead.

6. How to Select the Right Type of API?

You can think of each type of API as an answer to a simple question:

System API: What kind of data are we dealing with?
Process API: How do we handle that data?
Experience API: Who is the data meant for?

Here's a decision map that could come in handy:

Question	Use This API Type	Why
Do you need to access or abstract a data source, like a database, ERP, or CRM?	System API	It encapsulates and projects the SoR, providing stable and reusable access.
Is the data source external or legacy that needs to be translated into a specific domain?	System API	It protects the domain model by acting as an Anti-Corruption Layer (ACL).
Are you applying business rules or orchestrating logic across multiple systems?	Process API	It combines data, applies logic, and coordinates workflows.
Can the logic be reused across multiple channels or consumers?	Process API	It centralizes orchestration for consistency and reuse.
Are you customizing data for a certain frontend, channel, or consumer?	Experience API	It shapes payloads for UX needs, which separates the frontend from the backend logic.
Is the consumer a website, a mobile app, or a partner system?	Experience API	It optimizes for performance, payload size, and the needs of each channel.

7. How to Write Composable and Reusable APIs?

1. Focus on capabilities, not endpoints

Instead of asking, "What API do I need?", you might want to ask:

What can this domain do?
What building blocks can be reused? This shifts the discussion from “what to create” to “how to put it all together”.

2. Approach APIs as modular and discoverable units

Every API, whether it's a System, Process, or Experience API, should be:

Focused: Have a single responsibility.
Discoverable: Listed in a developer portal or catalog.
Composable: Designed to be orchestrated, not just consumed. This makes APIs feel more like building blocks rather than monoliths.

3. Rewire, don’t rebuild

When you need a new feature, consider alternative options before creating a new API:

Search for existing APIs that provide the data or functionality you need.
Put them together using Process APIs.
Expose them via Experience APIs. This approach speeds up delivery and cuts down on duplication.

4. Use ALC layers to enforce separation of concerns

System APIs are adapters to SoRs.
Process APIs are orchestrators of business logic.
Experience APIs are tailored views for consumers. Connecting these layers together, you can build flexible and composable systems that are easier to develop and maintain.

We can go back to the analogy that compares API-Led Connectivity to the MVC pattern. It’s a helpful way to understand how different API layers share their duties.

System API ≈ Model

Like the Model in MVC encapsulates data and business entities, the System API abstracts access to data sources like databases, ERPs, CRMs, etc.
It hides complexity and reveals clean, reusable interfaces for the rest of the architecture.

Process API ≈ Controller

The Controller in MVC handles orchestration, input processing, and coordination between the View and Model.
Similarly, the Process API orchestrates logic, combines data from multiple System APIs, and puts business rules into action.

Experience API ≈ View

The View presents data in a way that is best for the user or channel.
The Experience API works similarly, tailoring and customizing data for certain consumers such as mobile apps, web portals, or partners.

Why This Analogy Works

It reinforces separation of concerns.
It helps to understand where logic belongs.
It promotes a layered approach and emphasizes reusability. Of course, ALC is more infrastructure-focused and broader than MVC, but the ideas behind them are similar enough for learning and design discussions.

8. Does API-Led Connectivity Align with Domain-Driven Development?

Yes

Domain-Driven Design and API-Led Connectivity go well together. DDD tells you where to split your problem space into bounded contexts and models, and ALC gives you how to expose, compose, and consume those contexts via APIs.

Bounded contexts as API ownership. In DDD, you break your domain into bounded contexts, each with its own model, language, and rules. In API-Led Connectivity, those contexts are exposed through APIs — but there’s no strict 1:1 formula. A bounded context might be represented by a single API, or by several System, Process, and Experience APIs. The key is that APIs respect the boundaries of the context and consistently preserve its Ubiquitous Language across integrations and channels.
System APIs as Anti-Corruption layers. When integrating a legacy system or another bounded context, DDD says you should use an Anti-Corruption Layer to translate foreign models into your own. The same thing goes for ALC’s System APIs. They wrap around SoRs or external services, change payloads into terms of your domain, and keep your model safe from leaking external schemas.
Process APIs as application services. Within a bounded context, your domain services bring together aggregates, enforce business rules, and manage transactions. Similarly, ALC’s Process APIs compose multiple System APIs, set up workflows, and present broader operations in your Ubiquitous Language.
Experience APIs as facades or UI adapters. DDD keeps domain logic and presentation separate. ALC’s Experience APIs serve as presentation facades that shape and filter the output of Process APIs for specific channels like websites, mobile apps, and partners. They keep UI teams safe from complicated domains and let each channel grow on its own.

By combining DDD’s strategic slicing with ALC’s three-layer architecture, you get a system that is modular, well-governed, and highly cohesive. With this approach teams can work together to build, own, and enhance APIs that work well with domain models.

We’ve set the stage, but the real challenges show up when it’s time to implement.
In Parts 2 and 3, we’ll talk about real-world questions that teams often ask when they start using API-Led Connectivity.

This article is also available on LinkedIn and Medium.

DEV Community