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