Part 2 - Structure and Composition
API-Led Connectivity is a proven architectural pattern for separating data, business logic, and representations across APIs. Numerous articles have been written about its advantages, but putting them into practice often raises many questions.
We looked at the basics in Part 1.
Now, in Part 2, we'll dive into the questions that teams have to deal with when they start bringing this pattern to life.
1. Should a System API only connect to one SoR?
Yes
A System API should only connect to one System of Record.
A System API is meant to be a clean layer of abstraction over a single data source. This one-to-one relationship makes your architecture clearer and more flexible:
- Focus and simplicity: the API clearly shows a single source, which makes it easier to understand where data comes from and how it is structured.
- Reusability and stability: APIs that are linked to one SoR are easier to version, reuse, and change on their own as systems change.
- Fault isolation: If the SoR has issues, they affect only its API layer, which helps preserve the rest of the system from failures and makes debugging easier.
- Simplified governance: it's easier to enforce security policies and access rules.
This tight coupling keeps the System API remain predictable and stops it from becoming a hidden orchestration layer. The Process API is better for that purpose.
But there are some exceptions.
A System API may need to temporarily wrap multiple sources in some cases, such as when working with legacy systems or during a transition. For example:
- Bringing together several similar legacy databases to provide unified models for new systems.
- Connecting different parts of a fragmented ERP system.
- Serving read-only views from different sources with as little logic as possible. If you do break the one-SoR rule, it's important to clearly document the trade-offs and think about moving those concerns to a Process API later.
2. Can a Process API connect to a SoR directly without a System API?
No
It breaks the architectural separation of concerns that API-Led Connectivity is built on, which is to keep different parts of the architecture separate.
Here’s why it’s generally discouraged:
- Tight coupling to core systems: Process APIs shouldn't have code that gets data from core systems. Direct connections tie them to system-specific implementations, which makes them harder to maintain and change.
- Loss of reusability: Consumers can't use a consistent access layer without a System API in the middle. Every Process API may end up duplicating integration logic.
- Weakened security and governance: When every Process API talks to the SoR on its own, it's harder to enforce centralized policies like logging, authentication, or rate limiting.
There are scenarios where it might be acceptable:
- Rapid prototyping: Work needs to be done quickly, and architectural integrity is not important.
- Minimal or isolated systems: A small database used only by a single process might not need to be fully separated.
- Legacy transitioning: In older systems, Process APIs may temporarily access SoRs until System APIs are in place.
Even then, it's best to think of it as a temporary solution until the system can handle proper abstraction.
3. Can one System API call another System API?
No
A System API should not call another System API.
The goal of System APIs is to be direct abstractions of certain Systems of Record that are clean, focused, and independent. When one System API calls another, it adds layers of dependencies and coupling and breaks down boundaries.
Here’s why it’s usually avoided:
- Tight coupling: Each System API should be able to be maintained and tested on its own. When System APIs depend on each other, it can make integration patterns weak.
- Violation of architectural boundaries: System APIs are like contracts at the system level. When you link them together, they become orchestration, which is better suited to a Process API.
- Performance and reliability risks: Every new dependency increases latency and adds potential failure points, which makes monitoring and troubleshooting harder.
Here’s when it might be justifiable only as an exception.This is generally not recommended unless there is a strong architectural reason for it:
- Reuse of encapsulated logic: If a System API wraps up complicated access or transformation logic that is already encapsulated in another System API and is hard to copy, it might be smart to reuse it again.
- Facade patterns: When modernizing a system, a new System API might wrap a legacy one to provide a clean interface without changing the way the system works inside.
- Tightly coupled SoRs: Some systems, like ERP and payroll, are so dependent on each other that it might not make sense to show them separately.
If you decide to call another System API from your own, be careful of cascading failures. Also, think about whether a Process API might give you better separation and control.
4. Can a System API call other third-party or homegrown APIs?
Yes
A System API can call third-party or homegrown APIs, but only if those APIs accurately represent or add to the System of Record. Otherwise, it runs the risk of overstepping its bounds.
The goal of System APIs is to make it easy to access data and functionality from a single System of Record through clean, reusable interfaces. Sometimes, this source is an external API, like Salesforce, Stripe, or a proprietary inventory system, which is the SoR. In those situations, the System API acts as a wrapper or adapter that standardizes access.
Some other acceptable situations are:
- Acting as a gateway or compatibility layer for legacy or complicated external systems.
- Enhancing core data by calling external enrichment services like geolocation, fraud detection, or validation APIs.
- Providing interoperability when internal systems depend on external modules as part of their basic functionality.
Things to keep in mind:
- Avoid scope creep: If you're combining different services or adding logic that doesn't belong together, you're probably getting into Process API territory.
- Watch for instability or latency: External APIs can cause problems like rate limits, downtime, or long response times.
- Mind security and governance: Make sure you have the right authentication, follow the rules for handling data, and have clear monitoring when connecting to third-party systems.
In short, it's all about what you want to do. If the external API acts as the SoR or directly supports its role, it makes sense to wrap it in a System API. If not, you might want to use a Process API to handle the interaction instead.
5. Can a Process API call another Process API?
Yes
A Process API can call another Process API, especially when it makes sense to reuse orchestration logic. But beware of overuse, as it could make things more complicated or slow down performance.
Process APIs are meant to wrap up business logic and connect actions or data from different System APIs. However, calling other Process APIs makes sense in scenarios like these:
- Reusing orchestration: If you've already made complicated flows in a Process API, reusing them keeps the tested logic and avoids duplication.
- Composable services: Building modular, layered processes aligns with good microservices-style architecture. In bigger workflows, smaller Process APIs can be used over and over again.
- Domain separation: When different business domains are kept in separate Process APIs, they may need to call each other to work together.
Things to keep an eye on:
- Tight coupling: Too many chains can make dependencies hard to see and integrations weak. Each Process API should be able to be deployed and tested on its own.
- Latency and overhead: Every chained call adds processing time, which raises the risk of timeouts or slower performance.
- Limited traceability: It can be hard to debug failures across interdependent Process APIs when there isn't centralized logging or tracing.
If you do call another Process API, just keep in mind that it can complicate the system and affect performance. Keep it short and purposeful.
6. Can an Experience API call System APIs directly without a Process API?
Yes
An Experience API can call System APIs directly without a Process API if the logic is simple.
Experience APIs work on the presentation layer, changing data and interactions for end-user applications. When the goal is simple transformation or aggregation that doesn't need business orchestration, they can connect directly to System APIs.
When should you make direct calls:
- Simple data aggregation: The Experience API just gets data from a few places, formats it, and sends it on without any business logic or orchestration.
- Presentation-level formatting: Formatting numbers, dates, or currencies so they show up correctly in a specific location.
- Latency-sensitive endpoints: Removing the middle layer can speed up response times for apps that need to be fast.
- No shared logic: If the data handling isn't used in more than one channel, it's fine to put it in the Experience API.
But there are some risks:
- Drift into orchestration: When your Experience API starts applying rules or coordinating flows, it stops being just a presentation tool. This should be implemented in the Process API.
- Duplication across apps: If you need the same orchestration for mobile, web, and partner portals, you'll end up duplicating logic.
- Tight backend coupling: Experience APIs that rely heavily on the structure of System APIs may crash or require updates when those backends change.
Direct calls can work in situations where the UI is clean and specific. But adding a Process API keeps your layers clean and ready for the future when it comes to business rules, orchestration, or shared workflows.
7. Can a consumer app use a System or Process API directly without an Experience API?
No
It breaks the principles of API-Led Connectivity and creates long-term risks.
API-Led Connectivity separates responsibilities across layers to maintain modularity and maintainability. Experience API decouples consumers from the business logic. Although skipping the Experience API layer may seem easier, doing so will lead to numerous long-term issues.
Here’s why it’s generally avoided:
- Tight coupling to backend logic: When a System or Process API is called directly, the system becomes tied to how the backend works. If you change the structure or orchestration, the consumer app or frontend could break and might need to be rewritten.
- Tight coupling to the consumers: On the other hand, skipping the Experience API makes the system tightly coupled to the consumers. The business logic must be updated every time any existing consumer is changed or a new one is added to the system.
- UX optimization limitations: Lower-level APIs aren't designed for user experiences. They often send back raw, large data that isn't good for mobile, web, or partner channels. Experience APIs let you format responses for each consumer individually.
- Security gaps and blurred responsibilities: Providing consumers with direct access to System and Process APIs makes the entire system vulnerable. Security measures must be put inside those APIs to prevent that. It breaks the single responsibility principle, and the system becomes more akin to a monolith. Experience APIs act as a buffer that enforces authorization logic, permission checks, and access policies, which may be general or customized for a particular consumer.
8. Can an Experience API be reused between multiple consumers?
Yes, in specific cases
An Experience API can be used by more than one consumer, but only if their needs are the same and the API stays focused.
Experience APIs are designed to provide customized and formatted data to specific consumers. In some cases, reusing one It can be beneficial to reuse the same Experience API between consumers, like mobile apps on different platforms, if their data and behavior needs are similar.
When it is useful:
- Shared data functionality across platforms.
- Response formats that work for both consumers.
- Endpoints are compatible with all consumers.
- No endpoints are designed specifically for one consumer.
When to be careful:
- Input/output divergence: When the API has to handle requests and responses in different formats, it has to use conditional logic, which makes it more complicated and harder to maintain.
- Risk of bloating: Trying to serve all customers from one API can make it too complicated.
- Fragility: Changes or improvements to one platform may break another.
In short, reuse works when consumer expectations are the same. If they don't match, it's best to separate the Experience APIs so that each one stays optimized and easy to maintain.
In Part 3, we’ll continue answering real-world questions often asked by teams when they start using API-Led Connectivity.
Top comments (0)