What is an API and how do you design it?

An Application Programming Interface (API) is a well-defined contract that allows external consumers or separate software components to interact with your code without needing to know its internal implementation details. Designing a robust API requires careful consideration of naming conventions, endpoint routing, expected parameters, error management, and handling large data payloads.

1. The Core Mental Model: What is an API?

To understand an API, imagine you are writing a library that sorts integers, and another developer wants to buy and use it. They do not need to look at your sorting algorithms, memory allocation, or helper functions; they only need a documented way to interact with your code.

• Contract Over Implementation: An API defines what your code does and how to talk to it, not how it does it under the hood.
• Analogy to Programming Functions: An API is essentially a function call exposed over a network or software boundary. It consists of:
  • A distinct name (e.g., getAdmins)
  • Specific input parameters (e.g., groupID)
  • A defined return type (e.g., a list of Admin objects)
  • Predictable error conditions (e.g., group does not exist)

External Consumer / Client
   |
   | calls API contract (FunctionName, Parameters)
   v
API Endpoint / Microservice Boundary
   |
   | executes internal business logic (hidden from client)
   v
Returns structured response (JSON payload / Error code)

2. The API Design Checklist: The "What" and the "Where"

When sitting down to design an API, you must methodically walk through a core operational checklist:

1. Where does this belong? (Microservice Routing) If you operate a microservice architecture, locate the API in the service responsible for that domain. For example, finding group admins belongs strictly inside the Group Service.
2. What does it do? (Action Naming) The name of the API should directly reflect its core operation. If an endpoint is named getAdmins, it must return only admins, not additional extraneous data like unrelated group metadata.
3. What inputs are required? (Parameter Hygiene) Pass only the data necessary to complete the task. Avoid bloating your parameter list with optional flags or extra context unless there is a severe performance bottleneck forcing optimization.

3. Common API Design Pitfalls: Naming, Parameters, and Bloated Responses

Poor API design often stems from trying to make endpoints "future-proof" by packing too much into them. This results in heavy network payloads and high maintenance friction.

• The Over-Fetching Trap: Developers often stuff large response objects with extra data in the hope that callers won't need to change them later. This wastes network bandwidth and confuses consumers.
• The Kitchen-Sink Parameter Trap: Forcing callers to pass unnecessary configuration or auxiliary lists just in case. If an API accepts an excessive number of flags, its underlying behavior becomes unpredictable.
• Naming Violations: If your function is called getAdmins, but it also creates groups or updates membership states behind the scenes, your naming is misleading.

4. Translating Program Functions to HTTP Endpoints

When exposing your API over the web using HTTP protocols, you must map your functional actions onto standard HTTP verbs and uniform resource identifiers (URIs).

Example Mapping: Getting Group Admins

• Where (Routing): /api/v1/groups/{groupID}/admins (Including a version tag like v1 ensures smooth upgrades later).
• What (HTTP Method):
  • Using a GET request with query parameters or path variables if no complex request payload is needed.
  • Using a POST request if you are passing a structured JSON payload in the request body.

5. Side Effects, Atomicity, and Clean Operations

An API should execute a single, well-defined responsibility. Designing functions that perform hidden side effects damages system reliability and complicates testing.

• Avoid Hidden Side Effects: If an endpoint named setAdmins silently creates a non-existent group, adds missing members, and assigns admin roles all at once, it creates a massive side-effect footprint.
• Atomicity Challenges: If multiple operations are bundled into one call and part of it fails, partial state corruption can occur.
• The Correct Approach (Separation of Concerns):
  1. If a group does not exist, the client should receive an explicit 404 Not Found error.
  2. The client then calls a separate createGroup endpoint.
  3. Once created, the client invokes setAdmins. This preserves atomicity and keeps individual APIs clean and testable.

6. Handling Large Responses: Pagination vs. Fragmentation

When an API queries a large dataset (e.g., retrieving 200 detailed member profiles), returning everything in a single payload crashes performance and exhausts memory.

• Pagination (Client-Driven):
  • Gives responsibility to the client.
  • The client requests data in chunks using offsets or page limits (e.g., GET /members?offset=0&limit=10, then offset=10&limit=10).
• Fragmentation (Protocol/Server-Driven):
  • Typically used in server-to-server or microservice communication.
  • When a response exceeds safe buffer limits (e.g., 10 KB), the server breaks the response into numbered sequential packets (Packet 10, 11, 12) ending with an explicit termination packet.

7. Data Consistency, Caching, and Service Degradation

Designing production-ready APIs requires balancing data freshness against performance load under heavy traffic.

• Eventual Consistency vs. Strict Consistency:
  • Asking for getAdmins while another transaction is adding a third admin might return only two admins.
  • Developers must decide if they require strict (and slower) consistency or if eventual consistency is acceptable for their use case.
• Strategic Caching:
  • Serving read-heavy queries (like post comments or group lists) from a cache drastically reduces database load.
  • Stale data tolerance: Determine if users care if comments are 3 seconds old.
• Service Degradation (Shedding Load):
  • When databases or internal services are overwhelmed, gracefully degrade responses rather than crashing.
  • Instead of returning full user profiles with high-resolution avatars and metadata, strip the response down to bare essentials (e.g., just the user ID and name) to keep the system running under heavy loads.

Summary and Key Takeaways

• API as a Contract: An API defines what interactions are supported, hiding internal implementation details from external consumers.
• Function-Like Architecture: Think of APIs like programming functions: they require a clear name, precise parameters, expected return types, and explicit error definitions.
• Avoid Over-Fetching: Never stuff extraneous data into response objects just to make them "extensible"; keep payloads lean and targeted.
• Version Your Routes: Use versioning identifiers in your paths (e.g., /v1/) to safely roll out updates without breaking existing callers.
• Zero Side Effects: Avoid bundling multiple hidden actions into a single API; keep endpoints atomic and single-purpose.
• Manage Large Payloads: Use pagination for client-facing interfaces and fragmentation for heavy server-to-server data transfers.
• Optimize for Load: Balance strict database consistency with caching strategies and service degradation techniques to protect your backend during traffic spikes.