We explain how to design API architecture with brokers, speed up integrations, reduce risks, and improve security.
Watch on YouTube Watch on Rutube ___________________________________________ Application Programming Interfaces (API) enable data exchange between applications. For business, designing a reliable API architecture is critical: it allows you to connect services, automate tasks, and work more efficiently.
This article examines how designing the architecture and integrations of service API brokers helps companies increase profit, reduce errors, and improve customer experience.
YouTube
API architecture is the structure that defines how APIs are organized, how they interact with other systems, and how they provide functionality. A well-designed architecture makes APIs modular, scalable, and easy to maintain. This reduces maintenance costs and speeds up the delivery of new features.
Basic architecture elements - API Gateway: A centralized entry point for client requests that provides routing and security. - Service Registry: Stores information about available services, making them easier to discover. - API Management Layer: Tools for API design, testing, and monitoring. - Backend Services: Services that execute business logic. - Data Layer: Manages the data accessed by APIs. Table: business effectiveness of key API architecture elements
| Architectural element | Business impact for the enterprise | Tool/technology |
|---|---|---|
| API Gateway | Speeds time to market, lowers integration costs, and protects revenue through centralized security and access control. | Kong, Amazon API Gateway, Apigee, Tyk, Azure API Management |
| Service mesh (Service Mesh) | Improves system resilience, simplifies service scaling, and reduces operational risk through automatic discovery and traffic management. | Linkerd, Istio, Consul, AWS App Mesh, Connect |
| API Management Layer | Enables API monetization, improves partner service quality, and reduces TCO through lifecycle management, analytics, and policies. | Azure API Management, WSO2, Gravitee |
| Backend Services | It directly defines the product's value for the customer, affects how quickly the business responds to market changes, and minimizes the cost of fixing errors through high-quality implementation. | Development in Java, .NET, Node.js, Python, Go; Containerization (Docker, Kubernetes) |
| Data Layer | Provides the foundation for analytics that drives profit, ensures regulatory compliance, and supports a single source of truth across all integrated systems. | Relational databases (PostgreSQL, MySQL), NoSQL (MongoDB, Cassandra), caches (Redis), message brokers (RabbitMQ, Kafka,) |
Architectural styles Each API architectural style has its own characteristics and business use cases: 1. REST. Uses standard methods and the HTTP protocol to manipulate resources. REST is widely used because of its simplicity, readability, and compatibility with web technologies. It is ideal for web applications, mobile services, rapid prototyping, and projects that require high scalability. 2. SOAP.
This protocol is based on XML formatting with a focus on security and reliability. It is in demand in enterprise applications where standardized, secure data exchange matters, such as banking or the public sector. 3. GraphQL- is a query language and execution runtime for APIs created by Facebook developers. Clients request only the data they need. GraphQL improves overall performance by reducing the number of server requests.
This style is ideal for mobile apps with varying data needs, as well as for working with complex, interconnected data. 4. RPC. A protocol for calling functions on a remote server as if they were local. Its modern implementations (gRPC) provide high speed and security, which is relevant for microservice environments. Used for remote procedures that require a specific result, especially in compute-intensive workloads, while abstracting the details from the client.
A Service API Broker is a specialized architecture tool, a single entry and exit point for all interactions between applications and services, both internal and external.
Think of it as a dispatcher at a complex transport hub. The API broker reduces integration complexity and speeds up the rollout of new services.
Benefits of using API brokers: - Time savings: speed up the connection of new systems. - Reliability: ensure integration stability. - Governability: centralized API management. - Cost reduction: reduce development costs.
Broker vs. API Gateway: clarifying the terms
It is important to distinguish these often confused concepts: API Gateway: focuses primarily on external consumers. It is a facade for internal services.
Core tasks are routing, authentication/authorization of external users, rate limiting, caching, and protocol translation. Service API Broker (Service Broker/ESB): manages all interactions, including internal communication between services (microservices).
Beyond gateway functions, it often includes complex content-based routing, data format transformation, orchestration of action sequences between services, and guaranteed message delivery.
For most companies, API brokers become a key tool that helps reduce integration costs and improve system reliability. When designing the architecture, consider these principles: 1. Separation of concerns: An API broker lets each service focus on its core function while it handles integration. This reduces development complexity and increases the speed of introducing new solutions.
2. Statelessness: an API request must contain all the information needed to process it. This makes it possible to scale to 10,000 requests per second without losing availability, which is especially important for high-load B2B systems. 3. Resource-oriented design: APIs are structured around resources identified through URIs. The API broker routes requests to the correct resources, simplifying interaction. 4. Uniform interface: HTTP methods ensure compatibility. The API broker guarantees consistency in how they are used.
5. Layered system: introducing layers such as an API broker makes it possible to implement caching, load balancing, and security features, improving performance. 6. Versioning: API versioning prevents failures during updates. An API broker helps support multiple versions at the same time. 7. Security: using modern standards such as OAuth 2.0 or JWT protects data. API brokers centralize security management, reducing the risk of leaks.
8. Scalability: the architecture must handle growth in request volume. API brokers distribute load, ensuring stability. 9. Maintainability: modular design and clear documentation simplify maintenance. API brokers centralize API monitoring and management. 10. Support for event-driven architecture: for systems that require real-time data processing, API brokers can act as event hubs, enabling asynchronous communication.
These principles deliver significant benefits to companies: - Seamless integration: API brokers simplify connectivity between partner systems, reducing the time needed to set up integrations. - Resource Savings: Automating operations reduces costs.
Integrating CRM and ERP through an API broker reduces order processing time by 25%. - Improved security:Centralized access control is a key element in reducing threats related to data leakage. - Faster product launches: Fast integration of new services makes it possible to respond more quickly to market changes. - Stronger partner relationships: API brokers provide reliable data exchange, strengthening trust between partners.
Designing API architecture is a systematic process that directly affects integration speed, total cost of ownership, and the resilience of business processes.
Let's walk through each step to build an effective solution. 1. Analysis of goals and requirements.
At this stage, it is important to gather the key requirements.
Functional requirements describe what the API should do:
Non-functional requirements cover performance, security, and scalability, such as a 200 ms response time or support for 1000 concurrent users. Example:
For an e-commerce API, functional requirements include fetching the product assortment and placing orders.
1. Choosing an architecture style.The choice of architectural style determines how the API should interact with clients.
Main options (we covered the architecture styles in detail above): - REST: suitable for web applications where ease of integration matters (Microsoft Learn). - SOAP: suitable for complex transactions with high security requirements (banking systems).
- GraphQL: ideal for mobile apps where optimization matters. When choosing, consider: -
Project goals: REST for simplicity, SOAP for security, GraphQL for flexibility. -
Compatibility with existing systems and technologies. -
The team's expertise: REST is simpler for most developers. -
Future needs: GraphQL makes API evolution easier. Example:
For a mobile app, GraphQL optimizes requests, while for a banking system, SOAP provides reliability. 1. Resource design.This step defines which data and functions the API exposes.
Resources are business entities: "users", "products", "orders", each with unique identifiers. At this stage, it is important to: -
Identify the key entities: for example, in a blog API, "posts", "comments", "authors". -
Specify attributes: for a "user" - id, name, email. -
Set relationships: "user" has "orders", "order" contains "items". -
Use clear names: plural for collections (/users), singular for individual resources (/users/123). -
Avoid deep nesting: instead of /users/123/orders/456/items, use URIs for related resources. -
Support filtering and pagination: for example, /posts?author=456 to filter by author. 1. Define operations.Operations define how the client interacts with resources through HTTP methods: - GET:
Retrieves data (example: GET /users/123 - request for information about user ID 123). - POST:
Creates a new resource (example: POST /users - adds a new user). - PUT:
Fully updates the resource (example: PUT /users/123 - replaces all data for user 123). - PATCH:
Partially updates a resource - changes the specified fields (example: PATCH /users/123 - updating user 123's email). - DELETE:
Deletes the resource (example: DELETE /users/123 - deletes user with ID 123). Tips: -
Follow HTTP standards for intuitive design. -
Define the allowed methods for each resource. -
Account for authentication: for example, DELETE requires administrator privileges. -
Example:For /posts: GET /posts - list posts, POST /posts - create a post, DELETE /posts/123 - delete a post. 1. Version management.Lets you update the API without disruptions for clients.
Key strategies: - URI versioning: /v1/users, /v2/users - a simple and clear approach. - Headers: Accept: application/vnd.company.users.v1+json - flexible, but more complex. - Request criteria: /users?version=1 - less reliable. Tips: -
Plan new version releases and support for older ones. -
Ensure compatibility so v1 clients keep working. -
Notify users about deprecation of older versions in advance. -
Use URI versioning for simplicity (Stack Overflow). Example:
If v1 has /users and v2 adds /profiles, v1 clients keep working unchanged.
Problem: the company faced decentralized integrations between legacy systems, ERP, and CRM.
This slowed partner onboarding and increased support costs and the risk of failures.
The audit identified vulnerabilities caused by scattered access points and non-standardized API contracts. Solution: a centralized API broker platform based on _Platform V_ has been implemented. Results after 18 months: -
60% reduction in partner integration cycles (to 1-2 months); -
40% reduction in support costs; -
90% fewer incidents thanks to automatic retries and caching; -
Fast adaptation to new regulatory requirements without reworking systems
Checkpoint question - choosing technologies.
The platform determines implementation speed, flexibility, and total cost of ownership.
There are many solutions: from powerful enterprise platforms to flexible open-source tools.
Here is an overview of popular platforms and key trends.
- Enterprise/versatile: MuleSoft Anypoint Platform, IBM API Connect, Software AG webMethods, TIBCO Mashery. - Specialized in API Management: Google Apigee, Kong Enterprise, (+ EventBridge for asynchronous flows). - Open-Source:WSO2 API Manager, Gravitee.io, Apache Camel, NGINX (as the basis for the gateway).
- Service Mesh integration: Using technologies such as Istio or Linkerd to manage internal microservice communication (resilience, observability), while the broker/gateway handles external traffic and complex transformations.
You can read more about Service Mesh in our article [link to the Service Mesh article]. - API lifecycle automation: CI/CD
Tools for automated API deployment through stages (dev, test, prod) based on the schema. - Event-driven architectures (EDA):
Growing demand for asynchronous communication through messaging platforms (RabbitMQ, Kafka, NATS) to improve responsiveness and resilience.
The lack of clear, complete documentation makes life harder for developers using the API. Without clear guidance on methods, parameters, and possible errors, integration takes longer and costs more. For example, developers can spend up to 30% more time learning a poorly documented API. For the business, this means delays in launching new features and higher support costs.
An API without a versioning system creates problems during updates. Changes to an API often break existing integrations, leading to disruptions in business processes. For example, a company that updates its API without supporting the old version may face client downtime and, as a result, lost revenue. Versioning, for instance through the URL (/v1/users), helps avoid such risks.
Insufficient attention to security, such as the absence of HTTPS or weak authentication (for example, without OAuth 2.0), makes APIs vulnerable to attacks. A data breach can lead to reputational damage and financial risks.
Complex APIs with an excessive number of endpoints or a tangled structure raise development and maintenance costs. They also make integration harder for partners, slowing the time to market for new services. A simple design — for example, using RESTful principles — cuts development time by 20%.
Designing integration architecture with a service API broker is a strategic necessity for companies that aim for growth and resilience.
This is an investment that pays off through: - Lower operating costs for building and maintaining system integrations. - Faster time to market for products and services, creating a competitive edge. - Greater business process reliability and fewer losses from downtime. - Stronger data security and reduced risk of costly incidents and fines.
