API First Architecture

Theory and Implementation

5 Day(s)

🎯 LEARNING OBJECTIVES

By the end of this lecture, you will be able to:

Understand Software Architecture and its role.
Identify architecture components and relationships.
Understand architecture models and diagrams.
Evaluate key quality attributes.
Recognize common architecture patterns and pitfalls.
Apply basic architecture design and validation concepts.

🧠 PREREQUISITES

Basic Software Development knowledge.
Understanding of SDLC and Requirements.
Basic OOP and Database concepts.
Basic familiarity with UML is recommended.

1.Introduction to API First

What is?

API-First architecture/strategy is a new architecture approach the shift the mindset of software development for APIs to consider APIs as independent product, with different journeys in order to achieve business objectives, independent from the UX journey that may mislead/abuse the API architecture and design.

You can just imagine it if you just think that your final product is the APIs, and you will commercialize it alone, without UX.

It means, you have API as a product, so you have:

Product manager
Product Roadmap
And product lifecycle

As example, the target persona of your product (APIs) which will use your product, like mobile app, web app, and smart watch.

So, We are starting with the API, not the application.

So, It's about "How will you image the solution upon the API first, not how to build the API upon the design first solution".

Why?

Async Development
Reduce development Cost
Reduce time-to-market

Principles

Same like software engineering lifecycle, passing all journeys as the opposite diagram mentioning, considering that your product is APIs, including its documentation and journeys.

As a pre-requisites, We should build the culture, which implies the following principles:

Your API is a product
Foundational design, not ad hoc retrofit
Team collaboration and impact
API-first supports microservices
The API contract

Ten Process Steps

Step 1: Create API Micro-Service architecture according to DDD, which each object has the following attributes:

Who Am I? I'm Employee Class
What I know? I know my code, name, birthdate, current salary, current role.
What I do? I can Create employee, delete employee, activate employee, deactivate employee, update employee, and block employee, and unblock employee
What is my state? like : blocked employee, Unblocked employee, Active employee and Inactive employee

Step 2: Determine key domains

Step 3: Determine each domain lifecycle

Step 4: Model your architecture domains

Step 5: Model your architecture sequence diagrams

Step 6: Model your architecture state-chart diagrams

Step 7: Develop CRUD APIs according to data models characteristics

Step 8: Create the journeys according to the sequence diagrams, with validating the pre-requisites

Step 9: Create APIs to validate product states

Step 10: Create Security model for the APIs

API Improvement model

As opposite figure, We have consumer and publisher, They are shared improvement the model, due to the required improvement after design, as a nature of any product lifecycle.

Are You API First Company?

Since you have the following characteristics, you can consider yourself as API-First company:

You have APIs that operate and maintain your data models
You are providing you APIs as independent product
You make APIs available to your customers and partners as a source of your revenue stream
You know how to Manage and discover your APIs
You have standardized processes to build APIs
Your APIs is independent from any UX design

2. API Versioning

What Is It?

API versioning is a practice in software development that involves managing and maintaining different versions of an Application Programming Interface (API). An API is a set of rules and protocols that allows one software application to interact with and request services or data from another software component, such as a web service or library. API versioning is essential to ensure that changes and updates to an API do not break existing clients or applications that rely on it.

Why?

Compatibility
Preventing Breaking Changes
Client Isolation
Sunset enabling
Business security and governance (Like creating API banking platform using API first, and then building the application upon)

So, it meet the strategic approach for the enterprise driven from the business transformation team, according to the following perspectives:

How will you build your upcoming products
How will your external entities integrate with your product
How will you monetize your product
How APIs will cover your overall business

Approaches

Different deployment
Headers
URI routing

Process

Level 01:

•Change management

•Control integration touch points by TL

•Announcement model for integration touch points

•Application of unit testing for integration packages

Level 02:

Apply selected Versioning streategy
Enable support period for version minors (Quarter based)
Backward compatibility according to release management process, which may be monthly, or quarterly or yearly
Quarterly code refactoring process to reset minor version backward compatibility
Handle legacy Versions : Responses and stoppage

Level 03:

Application of design patterns: Aggregation pattern, to reduce the touch service, which gives the team the freedom for changing the signature
API Catalog Model completeness, which should be deployed on API management platform, like SWAGGER, including its documentation

Level 04:

Provisioning model for monetization: which will be used in the access of authentication and authorization, for the given tokens, to enable who can do what, and enrich monetization of your exposed APIs

3. API Versioning Consolidation

The practice is called API Version Consolidation or API Version Aggregation is mandatory when applying the API first approach.

Why it's needed:

Reduce maintenance overhead: Maintaining many versions leads to duplicated logic and higher testing costs.
Improve developer experience: Consolidated APIs are easier to understand, use, and document.
Encourage standardization: Forces consistency across versions, reducing divergence.
Simplify security and governance: Fewer versions mean fewer attack surfaces and simplified auditing.

Best Practices:

Deprecate old versions with clear timelines
1. 1. Review versions different scenarios
  2. Study scenarios consolidation approach
  3. Announce
  4. Cut-off date
  5. Staging testing
  6. Deploy together
Use semantic versioning (v1, v2, etc.).
Support backward compatibility within reason.
Communicate changes transparently with API consumers.

4. API Perofrmance Optimization Model

Inroduction

API performance is rarely caused by a single component. In a modern digital platform, a slow API can be the result of a combination of factors across the frontend, network, API gateway, application services, integration layer, database, infrastructure, and external dependencies.

For this reason, I developed an end-to-end API Performance Optimization Model that looks at performance as a complete journey rather than treating each API in isolation.

The objective is simple: identify the APIs that matter most, understand where the time is being spent, optimize the right layer, and continuously measure the impact.

From Measurement to Optimization

The first step is to establish a clear performance baseline.

We analyze APIs based on two critical dimensions:

Response Time — Which APIs are the slowest?

Request Volume — Which APIs are being called most frequently?

This creates a practical prioritization model. An API that is slow but rarely used may have limited business impact, while an API that is both slow and heavily consumed can become a major source of poor user experience and unnecessary infrastructure consumption.

Therefore, optimization starts with the APIs having the highest combination of latency and traffic volume.

Performance Across All Layers

Once an API is selected, the analysis moves across the complete technology stack.

Frontend / Mobile

We examine page behavior, number of API calls, payload size, lazy loading, unnecessary requests, and client-side processing.

Network

We evaluate network latency, connection establishment, TLS overhead, bandwidth, and communication paths.

API Gateway / WAF

We assess routing, policies, authentication, transformation, throttling, inspection, and other processing introduced before the request reaches the application.

Application / Service Layer

We investigate inefficient source code, excessive processing, synchronous dependencies, thread utilization, serialization, memory consumption, and architectural patterns.

Integration Layer

We analyze calls to external and internal systems, response delays, retries, connection pools, timeouts, and synchronous dependencies.

Database

We examine SQL execution, indexing, execution plans, locking, waits, partitioning, connection pools, and inefficient data access.

Infrastructure

We validate CPU, memory, network, storage, containers, JVM behavior, autoscaling, and resource contention.

The principle is straightforward:

Optimize the bottleneck, not the symptom.

A Controlled Optimization Cycle

Performance optimization should not become a continuous stream of isolated technical changes. It needs a controlled and measurable cycle.

For every selected API, we follow:

Measure → Diagnose → Optimize → Test → Deploy → Monitor → Validate

Every optimization must demonstrate measurable improvement before moving to the next API.

This allows us to answer the questions that matter:

Did response time actually improve?
Did throughput improve?
Did infrastructure consumption decrease?
Did the change introduce any functional or stability risks?
Did the improvement remain after deployment?

Five APIs Every Month

To make performance improvement continuous and manageable, the optimization program targets five APIs every month.

The selection is driven primarily by:

1. Lowest response time
Prioritize APIs with the poorest latency.

2. Highest request volume
Prioritize APIs that have the greatest consumption and business exposure.

3. Business criticality
Give additional priority to APIs that directly affect important customer journeys or critical business processes.

This creates a continuous optimization pipeline rather than a one-time performance exercise.

Monthly Cycle

Month 1

Identify the baseline → Select the top 5 APIs → Diagnose bottlenecks → Implement improvements → Validate results.

Month 2

Move to the next 5 priority APIs while continuing to monitor the previous improvements.

And continue the cycle month after month.

Measure the Outcome, Not Just the Change

The success of optimization should be demonstrated through measurable indicators such as:

Response Time
P95 / P99 latency and average response time.

Throughput
Requests processed per second.

Error Rate
Failures, timeouts, and rejected requests.

Resource Utilization
CPU, memory, database connections, threads, and infrastructure consumption.

User Experience
The actual improvement perceived by web and mobile users.

The real objective is not simply to make an API faster.

It is to make the entire digital journey faster, more stable, more scalable, and more efficient.

My Approach

I do not believe in optimizing everything at once.

The better approach is to prioritize, measure, understand the root cause, optimize at the correct layer, and prove the result with data.

By focusing on the five most impactful APIs every month, performance improvement becomes a measurable engineering capability rather than a reactive troubleshooting activity.

Performance is not a single-layer responsibility. It is an end-to-end engineering discipline.

5. API Traffic Management

1.Introduction

Modern applications expose APIs to web portals, mobile applications, kiosks, and external partners. Without proper traffic management, excessive requests can overload backend services, increase response times, and cause service outages. Malicious requests can also exploit application vulnerabilities or consume valuable resources.

To mitigate these risks, we use three complementary mechanisms: Web Application Firewall (WAF) to filter malicious traffic, rate limiting to enforce request quotas, and throttling to control traffic reaching constrained services. Understanding where and when to apply each mechanism is essential for designing secure, reliable, and high-performance APIs.

Real-world example: A vehicle-licensing API experiences a sudden traffic spike. The WAF blocks suspicious requests, API Connect enforces consumer quotas, and throttling protects the licensing backend from excessive concurrent processing.

2.WAF

The Problem

Public-facing APIs are exposed to attacks such as SQL injection, malicious payloads, automated abuse, and suspicious HTTP requests. Application-level validation alone may not provide sufficient protection at the system perimeter.

The Solution

A WAF inspects HTTP/HTTPS traffic and applies security rules before requests reach the protected application. Depending on the product, it can block malicious requests, filter suspicious sources, enforce request-size restrictions, and provide bot protection.

Practical Example

A request to a licensing API contains a SQL injection payload. The WAF detects the suspicious pattern and blocks the request before it reaches IBM API Connect or the backend service.

However, a legitimate API consumer exceeding its agreed request quota requires API traffic controls, not merely WAF security rules.

Implementation Guidelines

Deploy the WAF at the application perimeter.
Enable and tune appropriate security rules to minimize false positives.
Apply IP reputation, bot protection, and payload-size controls where supported.
Prevent clients from bypassing the WAF to reach backend services directly.
Monitor blocked requests, false positives, and inspection latency.

Expected Impact

Reduces exposure to web attacks, filters suspicious traffic, and prevents unnecessary malicious requests from consuming downstream resources.

3.Rate Limiting

The Problem

An API consumer may generate excessive requests, intentionally or unintentionally, consuming shared capacity and affecting other consumers. Without usage limits, one client can dominate API resources.

The Solution

Rate limiting defines how many requests a consumer, subscription, IP address, or API can make within a specified period. Requests exceeding the applicable limit can be rejected, commonly with HTTP 429 Too Many Requests.

Practical Example

A partner is permitted 100 requests per minute to a licensing API. When the partner exceeds that quota, APIC rejects additional requests according to the configured policy. Other consumers can continue operating within their own limits.

Implementation Guidelines

Define quotas according to consumer entitlements and backend capacity.
Apply limits per consumer, subscription, API, or expensive operation as appropriate.
Select an algorithm such as token bucket or sliding window based on the required traffic behavior.
Return consistent error responses and use Retry-After where appropriate.
Configure clients to use bounded retries with exponential backoff and jitter.
Verify whether limits are enforced globally or independently across gateway replicas.

Expected Impact

Enforces fair usage, protects API availability, and prevents individual consumers from exhausting shared resources.

4.Throttling

Even legitimate requests can overwhelm a backend when traffic arrives faster than the service can safely process it. This can cause resource exhaustion, database contention, increased latency, and cascading failures.

The Solution

Throttling controls the rate at which requests are admitted or processed. Depending on the implementation, excess requests may be delayed, queued within defined limits, or rejected.

Practical Example

A licensing integration can safely process 50 requests per second, but incoming traffic rises to 120 requests per second. A throttling policy constrains the traffic forwarded to the integration, helping protect it from overload.

For a latency-sensitive synchronous API, immediate rejection may be preferable to prolonged queueing. If work can be processed asynchronously, a bounded queue may be appropriate.

Implementation Guidelines

Establish limits using measured backend throughput and capacity.
Apply separate controls to constrained downstream integrations.
Use concurrency limits for long-running operations.
Define maximum queue depth and waiting time if queueing is necessary.
Combine throttling with timeouts, circuit breakers, and controlled retries.
Monitor rejected requests, queue depth, backend utilization, and p95/p99 latency.

Expected Impact

Protects constrained services, controls traffic spikes, and reduces the risk of backend overload and cascading failures.

How API timeout will be calculated?

The timeout should normally include the time spent waiting in the queue, especially when the timeout represents the caller's total response-time budget. However, the exact behavior depends on where the timeout is configured.

So : Response time = Queue Delay time + API response time

5. How the Three Mechanisms Work Together

Consider a licensing platform serving mobile applications, web portals, kiosks, and external partners.

WAF: Filters malicious HTTP requests and suspicious traffic at the perimeter.
Rate limiting: Enforces the request quota associated with each API consumer.
Throttling: Protects backend services by controlling the traffic they can safely process.
Backend resilience: Uses timeouts, concurrency limits, and circuit breakers to contain failures.

These mechanisms operate at different layers and should be configured according to their responsibilities.

6. Key Takeaway

WAF, rate limiting, and throttling solve different problems. The WAF protects against malicious traffic, rate limiting controls how much a consumer can request, and throttling controls how quickly requests reach or are processed by constrained services. A well-designed API architecture combines these controls to maintain security, fairness, availability, and predictable response times.