DEV Community: Shandor Sharvari

API-Led Connectivity - Practical Questions Answered - Part III

Shandor Sharvari — Tue, 04 Nov 2025 16:45:22 +0000

Part 3 - Implementation and Design Choices

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. In Part 2, we discussed some questions about the structure and composition of APIs.
In Part 3, we'll tackle real-world questions, often about implementation and design choices.

1. Should a System API return a domain model or a one-to-one mapping of data from SoR?

Domain model is better, but mapping is fine in specific cases

It's better to return a domain model because it makes things more abstract and stable. However, sometimes one-to-one mappings might be acceptable for internal or CRUD-based tasks.

System APIs work best when they expose a clean, stable domain model that abstracts the underlying System of Record. This approach has important architectural advantages:

Abstraction and decoupling: It protects consumers (like Process APIs) from backend volatility. For example, if a field in the SoR is renamed or its structure changes, your domain model stays the same and the API contract is safe.
Clear semantics: SoR schemas don't always show what the business wants, but they do show what is technically possible. A domain model helps show things like Customer, Order, or Invoice in ways that make sense for the business and are easier for other APIs to consume.
Cross-system consistency: When multiple SoRs model similar entities in different ways, System APIs can standardize and expose them in a single format, which makes integration easier and cleaner.

Direct SoR mapping is okay in some specific scenarios:

Admin or CRUD interfaces: Tools that need full control over raw fields and behaviors may need structures that don't change.
Legacy migration or pass-through access: If the purpose of the System API is proxying and replicating old systems without data transformation.

Even in those cases, it's best to keep them separate and document trade-offs.Tight coupling can expose internal parts and make integrations less stable.

2. Should Process or Experience APIs use domain models from lower layers, or should they map them to their own internal service models or DTOs?

Better to map, but direct use is sometimes okay

By default, mapping makes things clearer, separates concerns, and adds a layer of abstractions. Only use models again when they are stable, shared within the domain, and owned within the same boundary.

Think of each API layer as a boundary with its own language:

System APIs are based on SoRs.
Process APIs show how business logic and orchestration work.
Experience APIs meet the needs of consumers.

Mapping between models at each layer helps preserve that separation of concerns.

System API domain models: Use or Map in Process APIs?
It's best to map to internal models (DTOs).
Why?

Decoupling: System APIs expose data that can be reused, but Process APIs often need to change, add to, or combine that data for business logic. With mapping, you can change things without getting stuck with the way the System API is set up.
Resilience to change: If the System API changes (for example, by adding fields or renaming attributes), the DTO layer protects your Process API.
Semantic clarity: Process APIs use the language of business processes, not systems. Mapping helps show what you want to do.

Process API domain models: Use or Map in Experience APIs?
Again, mapping is better because Experience APIs should focus on consumer needs.
Why?

Tailored payloads: Mobile apps, web portals, and partner systems often need formats or field names that are different from each other.
Performance optimization: You might want to remove unused fields, flatten nested structures, or make content more relevant to consumers.
Channel independence: If two Experience APIs (like mobile and web) use the same Process API, mapping lets each one develop independently.

There are occasions when it is acceptable - and even better - to reuse upstream models without mapping them to internal DTOs for the sake of simplicity, performance, or alignment.

Read-Only, Pass-Through APIs: If a Process or Experience API is acting as a transparent proxy, passing data without changing or adding to it, mapping may not be needed. For instance, a customer lookup API that gets basic profile information from CRM without any business logic in between.
Stable, Shared Canonical Models: When teams share a well-defined, versioned domain model (like a shared CustomerDto or OrderModel) with clear ownership and contract stability, it's okay to reuse it across layers. This happens a lot when there is a centralized modeling team or a mature domain design across services.
Internal Tools or Trusted Consumers: In APIs that are only for internal use (like dev dashboards and admin tools), where:
- Change impact is minimal.
- Consumers understand the source model.
- A single team or a few small teams own all the layers and work together closely.
Pure Composition APIs: Sometimes, a Process API just collects data from several System APIs without making any significant changes to them. If the source APIs already return domain-aligned shapes, reusing their models saves time.
Thin Experience APIs: If an Experience API doesn't make many changes, like if it's just a pass-through layer for analytics dashboards, it might be fine to use the Process API model directly, especially if performance is important.

Mapping vs. Reuse Decision Matrix

Criteria	Map Upstream Models When	Reuse Upstream Models When
Layer Separation	Moving from System APIs to Process APIs or from Process APIs to Experience APIs	Models have the same concern or layer boundary
Model Ownership	Models are owned outside your context (e.g., SoR models)	Models are owned and versioned within your bounded context
Transformation Needed	Models require enrichment, filtering, or business-specific composition	Models are already shaped for its use
Consumer-Specific Shaping	Models are tailored to channel needs (e.g., UX or mobile optimization)	Consumer needs are similar
Change Risk from Upstream	Changes to the upstream schema are very likely to happen	Stable contracts and predictable changes
Governance and Contract Clarity	Each layer defines its own stable contract	A single team manages both sides or internal use
Prototyping or Internal Use	Structure should support long-term stability and reuse	Fast-moving use cases where simplicity matters

Layer Separation
- Map models for moving from System APIs to Process APIs or from Process APIs to Experience APIs.
- Reuse models if they have the same concern or layer boundary.

Model Ownership
- Map models if they are owned outside your context (e.g. SoR models).
- Reuse models if they are owned and versioned within your bounded context.

Transformation Needed
- Map models if they require enrichment, filtering, or business-specific composition.
- Reuse models if they are already shaped for its use.

Consumer-Specific Shaping
- Map models if they are tailored to channel needs (e.g., UX or mobile optimization).
- Reuse models if consumer needs are similar.

Change Risk from Upstream
- Map models if changes to the upstream schema are very likely to happen.
- Reuse models if contracts are stable and changes are predictable.

Governance and Contract Clarity
- Map models if each layer defines its own stable contract.
- Reuse models if a single team manages both sides or internal use.

Prototyping or Internal Use
- Map models if the structure should support long-term stability and reuse.
- Reuse models for fast-moving use cases where simplicity matters.

3. Which layer should enforce user permissions?

Experience API, though others can too

The Experience API layer should mostly enforce user permissions because it is closest to the user and best suited for customizing access based on identity, role, and context.
Depending on how complex and sensitive the logic and data being protected are, both Process and System APIs might include additional permission checks.

Experience API: Customizes access based on the user's role, identity, or channel:

Applies coarse-grained access control (for example, can the user see a certain part?).
Filters or masks fields (for example, hide private data from people who aren't admins).
Uses Attribute-Based Access Control or Role-Based Access Control that works with UI logic. Optimized for quick, user-centered decision-making.

Process API: Controls who can use business logic:

Validates roles within workflows (for example, can the user approve big bills?).
Coordinates policy engines and identity providers.
Interprets user context and compares it to business rules. Best for making access decisions based on the situation.

System API: Protects the data boundary:

Enforces strict data access control, especially in sensitive SoRs like patient records or financial data.
Acts as the last line of defense in case the checks higher up are bypassed.
Integrates with Anti-Corruption Layers or backend-level security.

Still, permission control and other security features should be made in a way that keeps APIs reusable.

Security and permission control should be layered and flexible so that protection is enforced without hardcoding behaviors that make it hard to use across channels, teams, or contexts:

Design APIs to check claims, not callers: Instead of tying logic to specific apps or users, use roles, scopes, or attributes passed in tokens so that any authorized user can interact with them in the right way.
Keep authorization context external and declarative: Access rules should be centralized in policy engines or gateways so that APIs can stay stateless and reusable.

To support reuse without compromising security, consider the following design practices:

Token scopes or claims: Design endpoints to check claims like read:customer or write:invoice, so that they can be used by multiple users but only by those with the right role.
Centralized identity provider: Use a shared identity provider, such as Entra ID, Auth0, Azure AD B2C, etc., to make sure that token issuance is consistent and claims are consistent across layers.
Multi-tenant support: Use tenant_id or caller_id in tokens to limit access to data safely between business units or domains.
API gateway abstraction: Let the gateway apply high-level policies, while APIs apply more specific, claim-based rules when necessary.

In real life, System APIs are usually made to be agnostic, flexible, and broadly reusable.
Their core responsibility is to expose data from Systems of Record without putting in any business- or consumer-specific logic. This neutrality supports:

Cross-domain reuse: Different Process or Experience APIs can use them at the same time without any problems.
Decoupling from consumer context: System APIs don't make any assumptions about who is calling or why they need the data.
Scalable security patterns: Access is typically controlled using scopes or claims, rather than hardcoded roles or caller IDs.

However, some domains require additional permission checks, especially where regulatory, privacy, or ethical constraints demand stricter controls:

Healthcare: Patient data often requires checks for contextual access, consent verification, and audit logging.
Finance: Account visibility, transactional access, and reporting are tightly controlled based on legal roles and jurisdiction.
Government or defense systems: Data segmentation, classification, and operator clearance all affect how APIs are made available.

So, yes, agnosticism is the default, but design must be able to handle sensitive data flows. The trick is to add enforcement (through claims, policy engines, or gateways) without hardcoding the logic into the API so that you can still use it in other places.

Access checks may be minimal or not needed at all when:

Serving data that is low-risk and read-only.
The entire call chain is trusted and tightly controlled, and the - Experience API enforces all relevant permissions.
The API is stateless and generic, and the caller is trusted to filter or restrict data.

Even then, always log, monitor, and document the rationale, because trust without visibility is a risky business.

4. Which layer is best for caching and retry policies?

All layers, but for different purposes

Caching and retry policies can technically be used at any layer, but their value and effectiveness depend on the layer's duties and nature.

Caching

System API: Cache responses from slow or read-heavy SoRs (like product catalogs and reference data).
Process API: Cache composed results if orchestration is expensive and data is stable.
Experience API: Cache UI-optimized payloads (like homepage data and dropdown lists) for better performance.

Retry Policies

System API: For temporary problems such as network glitches, timeouts from SoRs or 3rd-party systems.
Process API: For orchestrated calls to several systems, especially when one might fail from time to time.
Experience API: For critical operations, but only if the downstream system is idempotent and the user experience is clear to stop duplicate actions or inconsistent state.

Tip: You might want to think about applying retry and caching policies declaratively at the gateway level (like Azure API Management) to keep infrastructure logic out of your code and make centralized management easier.

5. Where is the best place to deal with pagination, filtering, and sorting?

In the System API

The System API is usually the right layer because it is closest to the data. This gives the best performance, especially when you query large datasets directly from Systems of Record that support efficient indexing and querying.

However, there are scenarios in which it makes sense to use these operations in other layers:

Process API: When you need to combine or aggregate data from several SoRs and no single system can do those tasks on its own. For instance, you could combine customer orders from CRM and ERP systems and then filter them to show only the most valuable ones.
Experience API: Good for lightweight pagination or consumer-specific filtering when working with small datasets, cached payloads, or for making the UI look different for each user. For instance, filtering a short list of dropdown values or ordering columns in a table based on the user's preferences.

6. Which layer is suitable for experimentation, like A/B testing and feature flags?

All layers, but for different purposes

Though the types of experiments vary between Experience and Process APIs, they are typically conducted in both. Experimenting with System APIs is dangerous.

Experience APIs are the right place for user-facing or consumer-specific experiments. Here are a few examples:

UI or personalization experiments: See what improves user satisfaction or interaction. For example, send different field names or formats to web and mobile apps.
A/B Testing: Measure conversion or engagement. For instance, use different algorithms for product recommendations depending on the user segment.
Feature Flags and progressive exposure: Introduce new capabilities gradually. Say, give 10% of users access to a new feature.

Because Experience APIs are closest to the user and are made to modify outputs without changing core logic, this experimentation is safe.

Process APIs can be used to experiment with features like business logic, orchestration paths, and data transformation behaviors that are not related to consumer-facing or UI logic:

A/B Testing of business rules: Compare the effect on conversion or revenue. For example, give 50% of users a 10% discount and give the remaining 50% a loyalty-based discount.
Alternate orchestration paths: Test reliability or performance of a new backend. Suppose you redirect certain requests from the legacy inventory system to the new one.
Retry or fallback strategy changes: Evaluate which strategy results in higher uptime or fewer errors. As an example, use exponential backoff for some users and fixed retry for others.
Caching Strategy Tests: Optimize performance and reduce load on SoRs. Let's say you try different caching durations for the same operation.
Rate limiting or throttling logic: Evaluate how well tiered performance limits work. As an example, impose more stringent rate limits on trial accounts while easing them for subscribers.
Data Aggregation Variants: Check to see if more data leads to better decisions. For instance, add more specific information, such as the average weekly purchase value, to summaries for specific users.

Experimentation with the Process API should concentrate on how it is gathered, processed, and chosen, rather than how data is presented. This aligns well with the API-Led Connectivity pattern, keeping responsibilities clear and allowing experimentation without compromising modularity.

System APIs should not be used for experimentation in most cases because they:

Are designed to expose and standardize SoR interfaces.
Must be stable and predictable.
Serve as the foundation for upstream APIs.

Changing how a System API behaves or what data it returns could break Process or Experience APIs.

However, as with any rule, there may be some exceptions, such as:

Changes in provider or infrastructure behind the scenes: Improve performance or reliability without changing the expectations of consumers. For example, testing a new database connector or query optimization as long as the contract remains the same.

The following table might help to make the right decision:

API Layer	Experimentation Type	Acceptable?	Notes
Experience API	A/B tests, user-specific formatting, feature flags	Yes	Safely tailors outputs to consumers
Process API	Business rule variation, routing logic, orchestration paths	Yes	Enables testing logic without exposing complexity
System API	Interface experiments, changing contract or data shape	No	Risky, may break upper layers
System API	Internal performance tweaks, like DB tuning	Maybe	Only if output/contract remains consistent

Experience API
A/B tests, user-specific formatting, feature flags are ** acceptable**.
An Experience API safely tailors outputs to consumers.

Process API
Business rule variation, routing logic, orchestration paths are acceptable.
A Process API enables testing logic without exposing complexity.

System API
- Interface experiments, changing contract or data shape are not acceptable, because they may break upper layers.
- Internal performance tweaks, like DB tuning may be acceptable, but only if output/contract remains consistent.

7. How to safely expose internal errors?

You can do the following to avoid giving away sensitive backend information while still giving useful feedback at the Experience layer:

Use a clear error schema, like "E5001: Service unavailable," to map internal errors to standard codes and messages. This way, you can show what you mean without giving away too much information.
Keep detailed logs private and share summaries publicly. For example, keep long stack traces and technical context in internal logs or observability tools, and send only error information that is relevant to the user or upstream system.
Use error translation middleware: Wrap backend responses so that system-specific types of failure (like database timeout) are turned into domain-aware messages (like "Product data not available").
Add correlation IDs to responses: Let Experience APIs expose identifiers that developers can use to trace issues without revealing internal architecture.
Don't send exception types or technical identifiers to the consumer: Messages like NullPointerException or SQLTimeout should stay behind the scenes.

Not only does this protect internal systems, but it also makes error handling more consistent and user-friendly across layers.

8. Why not provide the business logic in a package instead of creating a Process API? It could speed up response time and reduce latency.

Both approaches have their pros and cons

The right choice depends on what your system needs: Do you need speed and simplicity, or flexibility and reuse?

A package might be best if performance is the most important thing and your logic is fixed or very specific. A Process API is a better choice for the long term if your logic covers more than one service and changes over time.

Putting business logic into libraries like NuGet, Maven, and NPM has a lot of benefits, especially for performance-critical apps. Here are some of the main benefits:

Performance and low latency: Package code runs right in the application's process, so there are no network or service overheads. It's perfect for logic that needs to respond right away, like rendering a user interface, checking input, or processing on the client side. For instance, a high-throughput trading platform embeds its risk-scoring logic in a package instead of exposing it through an API. This guarantees that transactions are completed in minimal time during peak loads.
Easy testing and debugging: Developers can write unit tests for packaged logic without having to mock network calls or infrastructure. Also, running things locally makes behavior more predictable and easier to follow during development.
Development simplicity: There is no need to set up services or manage infrastructure. You can simply import the package and use the logic. It works best when development speed is more important than design. It's also very helpful for early-stage projects or MVPs. It's a quick way to add features to many services without having to build APIs.
Offline capabilities: Packages don't need to be connected to the network, so they're great for apps that work in low-bandwidth environments or offline modes. Think about mobile apps for field service that need to work in places with no internet access.
Strong encapsulation: Packaged logic can enforce strict modular boundaries, such as strong typing and self-contained units. It makes things clearer, easier to document, and simpler to move between projects. You can provide your functionalities to desktop apps, microservices, or CLI tools - all from the same codebase.

However, using packages might also cause duplication and limit visibility across systems.
Here is how Process APIs address the drawbacks of packaged logic:

Centralized control: When logic is spread out through libraries, each consumer has to take care of their own copy. You have to recompile and redeploy every app to update business rules. A Process API makes orchestration more centralized, so updates happen right away and are the same for all consumers.
Internal bug fixes: When an issue or bug is found in the system, it can be resolved within the API. The consumers don't need to be redeployed or recompiled. In contrast, packaged logic requires coordination with the teams that own the consumer code, as any bug fix involves updating the package, changing the consumer code, and redeploying it. Upstream consumers may also need to be updated as a result, which could have a cascading effect that increases deployment effort and complexity.
Runtime governance and monitoring: Process APIs live at the service boundary, so you can use policies like rate limiting, quotas, logging, and auditing. Local packages run in the app, which is great for speed but not for operations.
Faster innovation: With a Process API, you can implement experimentation like A/B testing on the business logic level. Packages need coordinated deployments, which slows down experimentation and responsiveness.

Tradeoff Summary

Approach	Pros	Cons
Packages	Fast, low-latency, easy unit testing	Hard to manage changes, no runtime control
Process API	Centralized, governed, dynamic orchestration	Higher latency, network overhead

Packages
- Pros: Fast, low-latency, easy unit testing.
- Cons: Hard to manage changes, no runtime control.

Process API
- Pros: Centralized, governed, dynamic orchestration.
- Cons: Higher latency, network overhead.

This article is also available on LinkedIn and Medium.

API-Led Connectivity - Practical Questions Answered - Part II

Shandor Sharvari — Thu, 23 Oct 2025 19:14:40 +0000

Part 2 - Structure and Composition

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.

This article is also available on LinkedIn and Medium.

API-Led Connectivity - Practical Questions Answered

Shandor Sharvari — Thu, 09 Oct 2025 14:10:23 +0000

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 Part 2 and Part 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 Part 2 and Part 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.

My Proven Code Review Method for Finding Bugs Others Miss

Shandor Sharvari — Thu, 25 Sep 2025 23:51:48 +0000

What Most Code Reviews Actually Catch

Most code review comments focus on conventions, variable names, styling, indentation, and missing unit tests. Simple and obvious mistakes are flagged too. Less frequently, reviewers comment on project and code structure, unhandled exceptions, basic optimizations, patterns, and best practices.

What Code Reviews Often Miss — And Why

But errors in algorithms and complex business logic are rarely highlighted during code reviews, along with performance bottlenecks and missed acceptance criteria. While these are difficult to catch, some can be spotted during code reviews, though they often require advanced approaches. Every issue found early significantly reduces the cost of fixing it and speeds up delivery.

So why do we usually miss these issues?

I think the main reasons are:

CR tools display code differently from IDEs we’re used to. Fonts, colors, and backgrounds don’t match, so our brains don’t focus in the same way.
Reviewers often read the code file-by-file in the order it appears in the CR. This can hide structure, context, dependencies, and execution order.
Little time is allocated for CRs. Everyone is busy with their own tasks.
Static code analysis, compilation warnings, and other advanced IDE features aren’t available in CR tools.

My Deep Review Workflow for Complex Changes

For small changes in familiar code, this isn’t a problem. But for brand-new apps, complex business logic, or deep refactoring, reading the code in a CR tool is not enough.

In those cases, I take the “hard way”:

Read the user story and acceptance criteria.
Review the code in the CR tool to understand the scope and spot complex areas.
Open the branch in my IDE and build it. Compiler warnings and static analysis suggestions are good indicators of areas to improve. For some reason, many of them are ignored during development.
Review from the entry point (for example, a Web API endpoint) or from updated business logic, following the runtime flow. Check the caller code too if it’s present.
Sometimes, it’s useful to open the documentation or even the third-party library code to ensure correct usage (e.g., if the thrown exceptions are handled in our code).
If I suspect input or edge case issues, I run the app and test it quickly, or even debug it.
Use an AI agent to analyze the code. Here I’ve shared useful AI prompts for it.
Check the code coverage.

This approach is complicated and time-consuming. It may take hours, but it’s usually worth it.

How I Write Review Comments

How I write comments matters too:

I explain my reasoning and sometimes link to docs or articles.
For repeating issues, I refer to the first comment or note that the fix applies in multiple places.
If I’m unsure about the code’s purpose or correctness, I ask for clarification in my comment.
I suggest authors mark comments as completed or reply to them as “done” rather than resolving them immediately, so I can double-check before approving the change. Sometimes I have a short call with the author after the review.

And how do you approach complex code reviews? What do you focus on?

My Favorite AI Prompts for Code Analysis and Optimization

Shandor Sharvari — Sat, 20 Sep 2025 08:22:23 +0000

AI agents have mastered boilerplate generation, short algorithms, and unit tests—speeding up routine and repetitive tasks.
But I tend to focus on code analysis and improvement suggestions. They’re especially helpful when writing performance-critical code or conducting intense code reviews.

Prompts I Use for Code Analysis

I usually ask the AI agent to analyze my code for:

Performance issues
High memory and CPU usage
Memory leaks
Poor scalability
Unbounded collections
Connection exhaustion
Unnecessary allocations
Deadlocks
Starvation
Inefficient loops and LINQ queries
Inefficient serialization/deserialization
Redundant computations
Blocking calls
Inefficient I/O operations
Improper resource disposal
Parallelization overhead
Inefficient exception handling
Unhandled exceptions
Unhandled edge cases
Algorithmic overcomplexity
Inefficient object lifetimes
Excessive thread creation and contention
Overuse of locks or synchronization primitives

Prompts I Use for Improvement Suggestions

I also ask it to explore potential improvements such as:

Performance optimizations
Memory usage optimizations
Concurrent or parallel execution
Simultaneous async calls
LINQ optimization or replacement with loops
Resource reuse
Read-only, frozen, or concurrent collections
Lazy evaluation
Weak references
Pooling of connections, arrays, objects, etc.

And what are your favorite prompts?