Why API design affects system usability in HLD - Design It to Understand It

Design: API Usability Impact System

Focus on API design principles affecting usability including endpoint structure, response format, error handling, and versioning. Out of scope are backend implementation details and database design.

Functional Requirements

FR1: Provide clear and consistent API endpoints for clients

FR2: Ensure API responses are easy to understand and use

FR3: Support error handling that helps developers quickly fix issues

FR4: Allow easy integration with different client applications

FR5: Maintain backward compatibility to avoid breaking existing clients

Non-Functional Requirements

NFR1: API response time should be under 300ms for 95% of requests

NFR2: Support up to 10,000 concurrent API calls

NFR3: Ensure 99.9% uptime for API availability

NFR4: Design must allow easy extension without breaking existing clients

Think Before You Design

Questions to Ask

❓ Question 1

❓ Question 2

❓ Question 3

❓ Question 4

❓ Question 5

Key Components

API Gateway or Proxy

Authentication and Authorization service

API Documentation and Developer Portal

Error Handling and Logging system

Versioning mechanism

Design Patterns

RESTful API design principles

Use of consistent naming conventions

Standardized error response format

API versioning strategies (URI versioning, header versioning)

Rate limiting and throttling for usability

Reference Architecture

Client Apps
   |
   v
API Gateway (handles routing, auth, rate limiting)
   |
   v
API Services (implement endpoints with consistent design)
   |
   v
Backend Systems / Databases

Additional components:
- Developer Portal (API docs, examples)
- Logging & Monitoring
- Error Handling Service

Components

API Gateway

Nginx or AWS API Gateway

Route requests, enforce authentication, apply rate limits

API Services

RESTful services using frameworks like Express.js or Spring Boot

Implement business logic with clear, consistent endpoints

Developer Portal

Static site generators or platforms like Swagger UI

Provide API documentation and usage examples

Error Handling Service

Centralized logging with tools like ELK stack

Capture and format errors to help clients debug

Versioning Mechanism

URI versioning or header-based versioning

Maintain backward compatibility and allow API evolution

Request Flow

1. Client sends request to API Gateway with authentication token

2. API Gateway validates token and checks rate limits

3. Request forwarded to appropriate API Service endpoint

4. API Service processes request and returns response with consistent format

5. If error occurs, API Service returns standardized error response

6. API Gateway forwards response back to client

7. Developer Portal provides documentation to help client understand API usage

Database Schema

Not applicable as focus is on API design and usability rather than data storage

Scaling Discussion

Bottlenecks

API Gateway becoming a single point of failure under high load

Inconsistent API design causing client confusion and integration delays

Poor error messages leading to increased support requests

Difficulty maintaining backward compatibility as API evolves

Solutions

Use multiple API Gateway instances with load balancing and failover

Enforce strict API design guidelines and review processes

Implement standardized error response formats with helpful messages

Adopt clear versioning strategies and deprecation policies

Interview Tips

Time: Spend 10 minutes explaining why API design impacts usability, 15 minutes on architecture and components, 10 minutes on scaling challenges and solutions, 10 minutes on answering questions

Clear and consistent API design reduces developer confusion and speeds integration

Standardized error handling improves debugging and user experience

Versioning is critical to maintain usability as APIs evolve

Scalability and availability of API Gateway affect overall system usability

Good documentation and developer support are part of API usability

Practice

1. Why is consistent naming important in API design?

easy

A. It hides errors from users.

B. It makes the API run faster.

C. It reduces the size of the API code.

D. It helps developers understand and use the API easily.

Solution

1. Step 1: Understand the role of naming in APIs

   Consistent naming helps developers quickly recognize and remember API functions and parameters.

2. Step 2: Connect naming to usability

   When names are clear and consistent, developers spend less time guessing and more time building.

3. Final Answer:

   It helps developers understand and use the API easily. -> Option D

4. Quick Check:

   Consistent naming = easier API use [OK]

Hint: Good names make APIs easy to learn and use [OK]

Common Mistakes:

• Thinking naming affects speed
• Assuming naming reduces code size
• Believing naming hides errors

2. Which of the following is the correct way to define an API endpoint for getting user details?

easy

A. GET /user/details

B. FETCH userDetails()

C. POST /getUserDetails

D. DELETE /user/details

Solution

1. Step 1: Identify the HTTP method for retrieving data

   GET is the standard HTTP method used to retrieve data without side effects.

2. Step 2: Check the endpoint path format

   /user/details is a clear, RESTful path indicating user details resource.

3. Final Answer:

   GET /user/details -> Option A

4. Quick Check:

   GET method + clear path = correct API endpoint [OK]

Hint: Use GET for fetching data in REST APIs [OK]

Common Mistakes:

• Using POST to fetch data
• Using DELETE for retrieval
• Using non-HTTP syntax like FETCH

3. Consider this API response JSON for a user request:

{"id": 101, "name": "Alice", "email": "[e-mail]"}

What will the client see if the API changes the key email to user_email without updating the client code?

medium

A. The client will show an error or empty email field.

B. The client will show the email correctly.

C. The client will crash immediately.

D. The client will display the email under a different key automatically.

Solution

1. Step 1: Understand client-server data contract

   The client expects the key 'email' to exist in the response to display the email.

2. Step 2: Analyze effect of key name change

   Changing 'email' to 'user_email' breaks the expected key, so the client cannot find the email value.

3. Final Answer:

   The client will show an error or empty email field. -> Option A

4. Quick Check:

   Key name change without client update = missing data [OK]

Hint: Client expects exact keys; changes cause missing data [OK]

Common Mistakes:

• Assuming client auto-updates keys
• Thinking client crashes always
• Believing client shows old key data

4. An API returns error messages as plain text strings. Developers complain it's hard to handle errors. What is the best fix?

medium

A. Return errors as HTML pages.

B. Remove error messages to avoid confusion.

C. Return error messages as structured JSON with error codes.

D. Send errors only in HTTP headers.

Solution

1. Step 1: Identify the problem with plain text errors

   Plain text errors lack structure, making it hard for clients to parse and react programmatically.

2. Step 2: Choose a structured error format

   Structured JSON with error codes allows clients to detect error types and handle them properly.

3. Final Answer:

   Return error messages as structured JSON with error codes. -> Option C

4. Quick Check:

   Structured errors improve client handling [OK]

Hint: Use structured JSON errors for clear client handling [OK]

Common Mistakes:

• Removing errors hides problems
• Using HTML breaks API consistency
• Sending errors only in headers loses detail

5. You are designing an API for a large system used by many developers. Which design choice best improves system usability and scalability?

hard

A. Return all data in one response to reduce calls, ignoring pagination.

B. Use clear, consistent naming with versioning and detailed error messages.

C. Use short, cryptic names to reduce URL length and avoid versioning.

D. Avoid documenting the API to encourage exploration.

Solution

1. Step 1: Consider usability factors

   Clear naming and detailed errors help developers understand and fix issues quickly.

2. Step 2: Consider scalability factors

   Versioning allows safe API evolution; pagination avoids large responses that slow systems.

3. Step 3: Evaluate options

   This option combines best practices for usability and scalability; others harm either or both.

4. Final Answer:

   Use clear, consistent naming with versioning and detailed error messages. -> Option B

5. Quick Check:

   Clear naming + versioning + errors = best API design [OK]

Hint: Combine clarity, versioning, and errors for scalable APIs [OK]

Common Mistakes:

• Choosing cryptic names to save space
• Ignoring pagination causing slow responses
• Skipping documentation hurting usability