APIs in Modern Software Design

An application programming interface (API) is a contract that lets one software component use data or functionality provided by another component. It defines what can be requested, what input is required, what comes back, and how errors are reported.

An API does not have to use the network. A library function, a browser feature, and a remote HTTP endpoint can all be APIs.

Why APIs Are Common

Modern applications are assembled from many components instead of keeping every feature in one codebase and process.

Software trend	How APIs are used
Web and single-page applications	Browser code requests data and actions from a server
Mobile applications	Mobile clients reuse the same backend services as web clients
Cloud services	Applications call managed storage, messaging, AI, and other services
Third-party integrations	Payment, analytics, maps, and communication features are consumed through APIs
Automation	CI/CD systems, infrastructure tools, tests, and monitoring systems control each other programmatically
Libraries and frameworks	Developers reuse maintained functionality instead of implementing it again

This reuse can shorten development time, but the application now depends on the API’s availability, security, documentation, and compatibility.

An API Is an Interface, Not the Implementation

The caller only needs to understand the contract. The provider can change its internal code without breaking callers, provided that the contract and its behaviour remain compatible.

Caller
  │
  │ request defined by the contract
  ▼
API ─────────► Implementation ─────────► Data store or another service
  ▲
  │ response defined by the contract
  │
Caller

A useful API contract documents:

• available functions or endpoints
• required parameters and request body
• response structure and status codes
• authentication and authorization requirements
• possible errors
• rate limits and quotas
• versioning and deprecation policy

OpenAPI is a standard, language-independent way to describe HTTP APIs. A small description might look like this:

openapi: 3.2.0
info:
  title: Catalog API
  version: 1.0.0
paths:
  /items/{itemId}:
    get:
      summary: Get one catalog item
      parameters:
        - name: itemId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Item found
        "404":
          description: Item not found

Key Insight: The documentation is part of the API. An endpoint that works but has no reliable contract is difficult to integrate, test, or maintain.

APIs at Different Levels

API type	Where it runs	Example
Library API	In the same process as the application	A cryptography or mathematics library
Browser API	Inside the browser	Fetch, DOM, Web Storage, or Geolocation
Framework API	Inside application code	Routing, sessions, logging, or rendering
Data access API	Between application code and a database driver or ORM	Executing a query or transaction
Remote API	Across a network	Payment, cloud, or application backend API

REST over HTTP is common for remote APIs, but API and REST API are not synonyms. Remote systems can also expose GraphQL, gRPC, WebSocket, event, or other interfaces.

An abstraction can reduce coupling without removing it completely. For example, a database access library may hide connection handling and common queries, but database-specific SQL and transaction behaviour can still make migration difficult.

APIs and Modular Design

Separating an application into modules with clear interfaces can provide:

• Separation of concerns: each module owns a focused responsibility.
• Parallel development: teams can work against an agreed contract.
• Isolated testing: a dependency can be replaced with a mock or test double.
• Independent change: internals can evolve while the interface remains compatible.
• Targeted scaling: heavily used components can receive more capacity.
• Technology choice: a component can use the runtime or data store that suits its workload.

These benefits do not require microservices. A modular monolith can use well-defined in-process APIs while remaining one deployable application. Microservices add independent deployment and scaling, but also introduce network failures, distributed data, observability, and operational overhead.

E-commerce Example

A web or mobile client can use one public entry point while the application is split into focused backend services.

flowchart LR
    subgraph Clients["Client applications"]
        Web["Web application"]
        Mobile["Mobile application"]
    end

    Gateway["API gateway"]

    subgraph Services["Application services"]
        Auth["Authentication"]
        Catalog["Catalog"]
        Orders["Orders"]
        Reviews["Reviews"]
    end

    AuthDB[("Identity store")]
    CatalogDB[("Catalog database")]
    OrderDB[("Order database")]
    ReviewDB[("Review database")]

    Web --> Gateway
    Mobile --> Gateway
    Gateway --> Auth
    Gateway --> Catalog
    Gateway --> Orders
    Gateway --> Reviews

    Auth --> AuthDB
    Catalog --> CatalogDB
    Orders --> OrderDB
    Reviews --> ReviewDB

The services may run on one machine, in one cluster, or in different locations. Spreading chatty services across distant regions usually increases latency and network cost. Placement must also account for availability, data residency, and recovery requirements.

Replacing a service’s internal technology is possible only if its contract remains compatible and its data can be migrated safely.

What an API Gateway Does

An API gateway is a central entry point between clients and backend services. Calling it a traffic cop is useful, but incomplete.

Capability	Purpose
Request routing	Send a request to the correct backend based on path, host, method, or another rule
Authentication and authorization	Verify identity or enforce access policy before traffic reaches a service
Rate limiting and throttling	Protect services and apply usage policies
Request or response transformation	Adapt client-facing data to a backend format
Aggregation	Combine results from multiple services into one client response
TLS termination	Handle encrypted client connections at a controlled entry point
Logging and metrics	Observe traffic, latency, failures, and usage
Caching	Reuse safe responses and reduce backend work

Gateways can route to load-balanced backends, and some products support health-based or regional routing. Multi-instance load distribution and multi-region failover may also require a load balancer, global traffic manager, DNS policy, or orchestration platform. A gateway alone should not be assumed to provide high availability.

Note: An API gateway handles runtime traffic. API management is a broader layer that can also include a developer portal, API catalogue, subscriptions, analytics, lifecycle policy, and monetization. Products often combine both roles.

Turning an API into a Product

An organization can expose an API through plans such as:

• a free plan with a small request quota
• a paid plan with higher quotas
• usage-based charging per request or unit of work
• partner-specific access to selected endpoints

The gateway or API-management platform can identify consumers, collect usage, and enforce plan policies. Billing is not built into every gateway. It may require an API-management product or a separate subscription and payment system.

Quotas also have product-specific behaviour. For example, AWS API Gateway documents usage-plan throttles and quotas as best-effort limits, not hard cost controls. API keys should identify a consumer or plan; proper authentication and authorization still need a dedicated mechanism.

One Data Store per Service

In the database-per-service pattern, a service owns its data and other services access that data only through its API or published events.

This allows a catalog service to use a search-oriented store while an order service uses a relational database with transactional guarantees. Each service can scale and change its storage independently.

The trade-offs are significant:

• queries across services become harder
• one business operation may span several transactions
• data may be temporarily inconsistent
• backups, monitoring, security, and upgrades cover more systems
• duplicate or read-optimized copies of data may be needed

Sharing one database is simpler for many applications. Separate stores are useful when service boundaries and independent scaling justify the added complexity.

Asynchronous Workflows

Long-running work does not need to keep the user’s request open. An order API can validate the request, record an initial state, and place further work on a queue.

sequenceDiagram
    actor User
    participant UI as Web or mobile app
    participant API as API gateway
    participant Orders as Order service
    participant Queue as Message queue
    participant Worker as Shipping worker

    User->>UI: Place order
    UI->>API: POST /orders
    API->>Orders: Route request
    Orders->>Orders: Validate and create pending order
    Orders->>Queue: Publish order work
    Orders-->>UI: 202 Accepted and status URL
    Queue-->>Worker: Deliver work
    Worker->>Orders: Update shipping status
    UI->>API: GET /operations/123
    API->>Orders: Read current status
    Orders-->>UI: Completed or failed

A possible HTTP exchange is:

POST /orders HTTP/1.1
Content-Type: application/json
Idempotency-Key: 70c4f693-3552-4d6e-92de-9cb14ac85525
 
{"itemId":"A123","quantity":1}

HTTP/1.1 202 Accepted
Location: /operations/123
Retry-After: 3
Content-Type: application/json
 
{"operationId":"123","status":"pending"}

202 Accepted means that processing was accepted, not that it completed successfully. The client needs a status endpoint, webhook, event, or another notification mechanism to learn the final result.

If the order resource itself is created immediately, the API may instead return 201 Created with an order whose status is pending. The exact response depends on what was completed before the response.

Warning: Asynchronous processing should not skip immediate validation. Reject malformed or unauthorized requests before queuing them. Use idempotency handling so a retry does not create duplicate orders or payments.

Network API Challenges

Remote calls introduce failure modes that local function calls do not have.

Challenge	Common response
Slow or unreachable service	Set timeouts; retry only suitable operations with backoff
Duplicate request after a retry	Use idempotency keys or naturally idempotent operations
Partial failure	Track state and design compensating actions
Breaking contract change	Use compatibility tests, versioning, and a deprecation window
Unauthorized access	Apply authentication, authorization, input validation, and least privilege
Difficult troubleshooting	Carry request IDs and collect logs, metrics, and traces
Excessive service-to-service traffic	Reconsider boundaries, aggregate calls, cache, or colocate services

TL;DR

• An API is a software contract; it is not limited to REST or network calls.
• APIs support modular design, reuse, isolated testing, and independent evolution.
• Microservices use APIs heavily, but APIs also work inside a modular monolith.
• An API gateway centralizes routing and common traffic policies.
• High availability may require load balancers, global routing, and orchestration in addition to a gateway.
• API monetization and hard quota enforcement depend on the chosen API-management platform.
• A database per service improves autonomy but makes cross-service data operations harder.
• Asynchronous APIs acknowledge work quickly and provide a way to track the final result.
• Documentation, testing, security, versioning, and observability are part of operating an API.

Resources

• API definition — MDN
• OpenAPI Specification
• API gateways in microservices — Microsoft Azure Architecture Center
• Asynchronous Request-Reply pattern — Microsoft Azure Architecture Center
• Database-per-service pattern — AWS Prescriptive Guidance
• API Gateway usage plans and API keys — AWS
• Apigee monetization overview — Google Cloud

Note: The standards and product behaviour referenced here were checked against official documentation in July 2026. Gateway features vary between products and deployment models.