System Design (LLD)API & Interface Design

What Is a Good API?

LevelIntermediate

Duration60 mins

TopicAPI & Interface Design

2 / 4

Usability Principles

Beyond Correctness: The Art of Usable APIs

An API can fulfill every contract perfectly—accepting all valid inputs, returning all specified outputs, throwing all documented errors—and yet be a terrible API to use. Technical correctness is necessary but insufficient. The best APIs are not just correct; they're usable.

Usability in API design is the difference between a developer integrating your API in 20 minutes versus spending 2 hours reading documentation, trying variations, and debugging cryptic errors. It's the difference between excited adoption and grudging acceptance. It's the difference between an API that spreads by word of mouth and one that survives only due to lack of alternatives.

Usability isn't a soft skill—it's a design discipline with well-established principles that can be systematically applied to create APIs that feel intuitive, predictable, and even delightful to use.

What You Will Learn

By the end of this page, you will understand: (1) Core usability principles including the Principle of Least Astonishment, (2) How to design discoverable, self-explanatory APIs, (3) The power of progressive disclosure in managing complexity, (4) Strategies for reducing cognitive load through simplicity and familiarity, and (5) How to make the common case simple while enabling advanced use cases.

The Principle of Least Astonishment

The Principle of Least Astonishment (POLA), also called the Principle of Least Surprise, is perhaps the most fundamental usability principle in API design:

An API should behave the way users expect it to behave.

This sounds obvious, but it has profound implications. Every design decision should be evaluated through the lens of "What would a developer reasonably expect here?" When reality matches expectation, the API feels intuitive. When there's a mismatch—even a small one—developers stumble.

Astonishment creates cognitive friction:

Common Sources of API Surprise

•Unexpected return values: array.sort() modifies in-place AND returns the array (which one am I supposed to use?)
•Inconsistent parameter ordering: substring(start, end) vs slice(start, length) vs substr(start, length)
•Silent failures: Operation succeeds but does nothing because of an undocumented precondition
•Side effects in getters: getValue() that modifies internal state
•Asymmetric operations: add() that takes an object, but remove() that takes an ID
•Type coercion surprises: JavaScript's '5' + 3 = '53' but '5' - 3 = 2
•Unusual defaults: A creation operation that automatically publishes, or a delete that's permanent without warning

Analyzing Expectations:

To apply POLA, you must understand where expectations come from:

Language conventions: What do similar operations typically do in this programming language?
Domain conventions: What do similar operations mean in this problem domain?
API conventions: What patterns have you established elsewhere in this API?
General computing conventions: What do developers generally expect from operations like "get," "create," "delete," "update"?

When multiple conventions conflict, prefer the convention closest to the user's mental model—typically domain conventions for domain operations, and computing conventions for technical operations.

LeastAstonishmentExamples.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
// ❌ Astonishing: Non-intuitive behavior
class OrderService {
    // Returns null on success, error message on failure
    // Why would success return null? Unexpected!
    createOrder(items: Item[]): string | null { /* ... */ }
    
    // Updates and deletes always succeed (even if entity didn't exist)
    // User can't tell if their intent was fulfilled
    updateOrder(id: string, updates: Partial<Order>): void { /* ... */ }
    
    // Returns the number of items, but modifies the cart (!)
    // Getter with side effect - extremely surprising
    getItemCount(): number { 
        this.lastAccessTime = Date.now(); // Hidden side effect!
        return this.items.length;
    }
}
 
// ✅ Unsurprising: Intuitive behavior
class OrderService {
    // Returns the created order on success, throws on failure
    // Standard pattern that developers expect
    createOrder(items: Item[]): Order { /* ... */ }
    
    // Returns the updated order, throws if order doesn't exist
    // User knows their intent was fulfilled or why it wasn't
    updateOrder(id: string, updates: Partial<Order>): Order { /* ... */ }
    
    // Pure getter with no side effects
    getItemCount(): number { 
        return this.items.length; 
    }
    
    // Explicit method for recording access (if needed)
    recordAccess(): void {
        this.lastAccessTime = Date.now();
    }
}

Testing for Astonishment

Ask colleagues unfamiliar with your API: "What do you expect this method to do?" If their expectation differs from reality, you have an astonishment problem. The fix might be renaming, restructuring, or adding clarity through documentation—but the best fix is usually to change the behavior to match expectations.

Discoverability: Self-Explaining APIs

A discoverable API is one that developers can learn through exploration. With good discoverability, developers can figure out how to use your API by reading method names, exploring available operations, and following intuitive patterns—without constantly referencing documentation.

Why discoverability matters:

Reduces time to first success
Lowers learning curve
Improves developer experience and satisfaction
Reduces support burden
Enables IDE-driven exploration (autocomplete, type hints)

Principles of discoverable design:

Elements of Discoverability

•Intention-revealing names: Method names should express what they do, not how. calculateShippingCost() not runShippingAlgorithm()
•Consistent vocabulary: Use the same term for the same concept. Don't switch between 'user', 'account', 'member', and 'profile' randomly
•Logical grouping: Related operations should be co-located. All user operations on UserService, not scattered across the codebase
•Progressive complexity: Start with simple, common operations that suggest more advanced options
•Meaningful return types: Return types should suggest what you can do next
•Rich type information: Types that enable IDE autocomplete, code navigation, and inline documentation

Names as Documentation:

Good names are the first line of documentation. They should be:

Naming Quality Criteria
Quality	Description	Poor Example	Better Example
Specific	Names should convey precise meaning	process()	validatePaymentMethod()
Unambiguous	Only one reasonable interpretation	handleData()	persistUserProfile()
Consistent	Similar patterns for similar operations	getUser() / fetchOrder()	getUser() / getOrder()
Pronounceable	Can be spoken aloud in discussion	procUsrRcrd()	processUserRecord()
Searchable	Easy to find via text search	x, tmp, data	orderTotal, tempFilePath
Domain-aligned	Uses language of the business domain	updateFlag()	activateSubscription()

The Fluent Interface Pattern:

Fluent interfaces maximize discoverability by making the next possible action obvious through method chaining:

FluentInterface.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// Fluent interface: Each return type suggests the next action
const query = db.users()
    .where('active', true)            // Returns ConditionBuilder
    .orderBy('createdAt', 'desc')     // Returns SortBuilder
    .limit(10)                        // Returns Limiter
    .select('id', 'name', 'email')    // Returns SelectBuilder
    .execute();                        // Returns Promise<User[]>
 
// The type system guides discovery:
// After .where(), IDE suggests: and(), or(), orderBy(), limit(), select()
// After .orderBy(), IDE suggests: thenBy(), limit(), select()
// After .limit(), IDE suggests: offset(), select(), execute()
// After .select(), IDE suggests: execute()
 
// Each step narrows possibilities, guiding developers through the API
 
// The Builder Pattern enables discoverability for complex object construction:
const notification = NotificationBuilder
    .create()
    .to('user@example.com')
    .withSubject('Your order shipped!')
    .withBody('Track your package at...')
    .withPriority('high')
    .schedule(tomorrow)
    .build();
    
// Without builder, developers would face:
// new Notification(to, subject, body, null, null, priority, null, schedule, ...)

IDE as Partner

Modern IDEs are powerful discovery tools. Design your API to leverage them: use rich type information, provide JSDoc/docstrings that appear in tooltips, organize related methods on the same object, and use return types that suggest next steps. A well-typed API essentially documents itself through autocomplete.

Progressive Disclosure

Progressive disclosure is a design principle borrowed from user interface design: reveal complexity gradually, showing simple options first and exposing advanced options only when needed.

APIs often fail by either:

Overwhelming beginners: Exposing every option upfront, making simple tasks feel complex
Handicapping experts: Hiding advanced capabilities so deeply that power users can't access them

Progressive disclosure solves both: make simple things simple, and complex things possible.

No Progressive Disclosure

•10 required parameters for basic operation
•Must understand entire config before starting
•Advanced and common options mixed together
•Can't do simple things simply

With Progressive Disclosure

•1-2 parameters for basic operation
•Sensible defaults for common cases
•Advanced options on specialized types
•Simple and complex each have a clean path

Implementation Strategies:

1. Sensible Defaults:

Every optional parameter should have a sensible default. The 80% use case should require minimal configuration.

SensibleDefaults.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
// ❌ No defaults: Every option required
function createHttpClient(
    baseUrl: string,
    timeout: number,
    retries: number,
    retryDelay: number,
    headers: Record<string, string>,
    interceptors: Interceptor[],
    cacheConfig: CacheConfig,
    certificateValidation: boolean,
    followRedirects: boolean,
    maxRedirects: number
): HttpClient { /* ... */ }
 
// Usage requires understanding everything:
const client = createHttpClient(
    'https://api.example.com',
    30000,    // What's a good timeout?
    3,        // How many retries?
    1000,     // What delay? Exponential?
    {},       // Any headers?
    [],       // Interceptors?
    ???,      // What's CacheConfig?
    true,     // Why would I not validate?
    true,     // Why would I not follow redirects?
    10        // 10 redirects?
);
 
// ✅ Progressive disclosure with smart defaults
interface HttpClientOptions {
    timeout?: number;          // Default: 30000ms
    retries?: number;          // Default: 3
    retryDelay?: number;       // Default: 1000ms with exponential backoff
    headers?: Record<string, string>;
    interceptors?: Interceptor[];
    cache?: CacheConfig | boolean; // true = default caching
    validateCertificates?: boolean; // Default: true
    followRedirects?: boolean | number; // true = follow (max 10)
}
 
function createHttpClient(
    baseUrl: string,
    options: HttpClientOptions = {}
): HttpClient { /* ... */ }
 
// Simple use case: just works
const simple = createHttpClient('https://api.example.com');
 
// Customized use case: override what you need
const custom = createHttpClient('https://api.example.com', {
    timeout: 60000,
    retries: 5
});
 
// Advanced use case: full control available
const advanced = createHttpClient('https://api.example.com', {
    timeout: 60000,
    retries: 5,
    retryDelay: 500,
    headers: { 'X-Custom-Header': 'value' },
    interceptors: [loggingInterceptor, authInterceptor],
    cache: { maxAge: 3600, staleWhileRevalidate: true },
    validateCertificates: false, // Explicit dev override
    followRedirects: 5
});

2. Layered APIs:

Provide multiple entry points at different abstraction levels:

LayeredApiDesign.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// Layer 1: High-level convenience methods (80% of users)
class FileStorage {
    // Simple: upload a file, get a URL
    async uploadFile(file: File): Promise<string> {
        return this.uploadWithOptions(file, {});
    }
}
 
// Layer 2: Configurable methods (15% of users)
class FileStorage {
    async uploadWithOptions(file: File, options: UploadOptions): Promise<UploadResult> {
        const request = this.buildUploadRequest(file, options);
        return this.executeRequest(request);
    }
}
 
// Layer 3: Full control (5% of users - library authors, power users)
class FileStorage {
    buildUploadRequest(file: File, options: UploadOptions): UploadRequest { 
        /* ... */ 
    }
    
    async executeRequest(request: UploadRequest): Promise<UploadResult> {
        /* ... */
    }
    
    // Full access to underlying client
    getStorageClient(): StorageClient { /* ... */ }
}

The Rule of Three Levels

Design APIs with three abstraction levels in mind: (1) Simple methods for common cases - minimal parameters, sensible defaults; (2) Configurable methods for custom cases - options objects, builder patterns; (3) Low-level access for advanced cases - access to underlying primitives. Most users stay at level 1, but levels 2 and 3 are there when needed.

Simplicity: Reducing Cognitive Load

Simplicity in API design means reducing the cognitive effort required to understand and use the API. This isn't about dumbing down functionality—it's about organizing complexity so each individual interaction is straightforward.

Cognitive load in API usage:

Developers have limited working memory. Every concept, parameter, and special case consumes cognitive resources. When an API demands too much simultaneously, developers make mistakes, take longer, and feel frustrated.

Simplification strategies:

Strategies for Simplicity

•Single responsibility per method: Each method does one thing well. Avoid multi-purpose Swiss Army knife methods.
•Minimal parameter counts: Fewer parameters mean fewer decisions. Aim for 0-3 required parameters.
•Obvious parameter order: When multiple parameters are needed, order them intuitively (subject before predicate, source before destination).
•Orthogonal concepts: Each concept should be independent. Learning one doesn't require understanding another.
•No hidden modes: Behavior shouldn't depend on invisible state. Each call should be understandable in isolation.
•Predictable patterns: Once developers learn a pattern, it should apply everywhere in the API.

The Cost of Clever:

Clever APIs—those that use advanced language features, sophisticated patterns, or non-obvious conventions—often sacrifice usability for elegance. Unless the cleverness provides significant benefits, prefer straightforward code that any developer can understand.

SimpleVsClever.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
// ❌ Clever: Operator overloading and fluent DSL
const results = users
    | where(u => u.active > true)   // Custom | operator
    << order('name')                 // Custom << operator
    >> take(10);                     // Custom >> operator
    
// Looks elegant, but:
// - Requires learning custom operators
// - Breaks tooling expectations
// - Hard to debug (what does | actually do?)
// - Unfamiliar to new developers
 
// ✅ Simple: Standard method calls with obvious names
const results = users
    .where(u => u.active === true)
    .orderBy('name')
    .take(10);
 
// Instantly familiar:
// - Standard method chaining
// - Clear method names
// - Debuggable step-by-step
// - Obvious to any JavaScript/TypeScript developer
 
// ❌ Clever: Magic string parameters
db.query('users', 'active:true,role:admin', 'name,-createdAt');
 
// What do these strings mean? Users must check documentation
 
// ✅ Simple: Structured parameters with types
db.query({
    table: 'users',
    where: { active: true, role: 'admin' },
    orderBy: [
        { field: 'name', direction: 'asc' },
        { field: 'createdAt', direction: 'desc' }
    ]
});
 
// Self-documenting, type-checked, IDE-friendly

Complexity Budget:

Every API has a complexity budget. Some complexity is unavoidable—the domain itself may be complex. The question is where to spend that budget.

Spend complexity on domain problems: If the problem domain is genuinely complex, it's acceptable for the API to reflect that complexity.
Don't spend complexity on API mechanics: The overhead of using your API should be minimal. Protocol, authentication, error handling, and serialization should be simple.
Make the common case cheap, the advanced case possible: Developers doing common tasks shouldn't pay the cognitive cost of advanced features they're not using.

Simple ≠ Simplistic

Simplicity isn't about removing features—it's about organizing complexity. A simple API for a complex domain still handles the complexity; it just presents it in digestible pieces. The goal is to make each individual interaction simple, not to reduce the API's power.

Consistency: Patterns That Transfer

Consistency means that once developers learn how one part of your API works, they can apply that knowledge to other parts. Inconsistency forces developers to learn each operation as a special case; consistency lets them learn patterns that apply everywhere.

Consistency operates at multiple levels:

1. Internal Consistency (within your API):

All operations in your API should follow the same patterns:

InternalConsistency.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
// ❌ Inconsistent: Every resource uses different patterns
interface InconsistentApi {
    // Users: CRUD with objects
    createUser(data: UserData): User;
    getUser(id: string): User | null;
    updateUser(id: string, data: Partial<UserData>): User;
    deleteUser(id: string): void;
    
    // Orders: Different naming, different patterns
    newOrder(items: Item[]): Order;           // Why 'new' not 'create'?
    fetchOrder(orderId: number): Order;       // Why 'fetch' not 'get'? Why number not string?
    modifyOrder(order: Order): Order;         // Why pass full object not ID?
    removeOrder(id: string): boolean;         // Why return boolean not void?
    
    // Products: Yet another pattern
    addProduct(name: string, price: number): string;  // Returns ID, not object?
    product(id: string): Promise<Product>;    // Async when others aren't?
    // No update method?
    deleteProduct(id: number): void;          // ID is number now?
}
 
// ✅ Consistent: Unified patterns across all resources
interface ConsistentApi {
    // All resources follow the same pattern
    createUser(data: UserData): User;
    getUser(id: string): User | null;
    updateUser(id: string, data: Partial<UserData>): User;
    deleteUser(id: string): void;
    listUsers(query?: QueryOptions): User[];
    
    createOrder(data: OrderData): Order;
    getOrder(id: string): Order | null;
    updateOrder(id: string, data: Partial<OrderData>): Order;
    deleteOrder(id: string): void;
    listOrders(query?: QueryOptions): Order[];
    
    createProduct(data: ProductData): Product;
    getProduct(id: string): Product | null;
    updateProduct(id: string, data: Partial<ProductData>): Product;
    deleteProduct(id: string): void;
    listProducts(query?: QueryOptions): Product[];
}
 
// Now learning one resource teaches you all resources

2. External Consistency (with platform conventions):

Your API should align with conventions developers already know:

Platform Conventions to Respect
Convention Source	Examples to Follow	Violation Impact
Language idioms	JavaScript uses camelCase, Python uses snake_case	Feels foreign, triggers constant mental translation
Ecosystem standards	HTTP libraries return Response objects with status, headers, body	Breaks expectations from other libraries
Framework patterns	Express middleware signature: (req, res, next)	Developers struggle to integrate
Popular APIs	Stripe's resource.action() pattern	Misses opportunity to leverage existing knowledge

3. Temporal Consistency (across versions):

Patterns should remain consistent across versions of your API. Introducing new patterns in new versions fractures the developer's mental model and complicates codebases that use multiple versions.

The Consistency Checklist:

Applying Consistency Systematically

•Naming patterns: If one resource uses getUser(), all resources should use get{Resource}(), not fetch{Resource}() or find{Resource}()
•Parameter patterns: If one method takes (id, data), similar methods should use the same order
•Return patterns: If one method returns Entity | null, similar methods shouldn't throw NotFoundException
•Error patterns: Consistent error types, codes, and messages across all operations
•Async patterns: If some operations are async, similar operations should be async too
•Null/undefined patterns: Consistent treatment of missing values throughout the API

The Consistency Tax

Consistency sometimes conflicts with what might be locally optimal for one method. The consistency tax is worth paying: global consistency across your API is more valuable than local perfection for any individual method. When in doubt, favor the pattern developers already know.

Affordance and Constraints

In design theory, affordance refers to properties that suggest how an object can be used—a door handle affords pulling, a flat plate affords pushing. Constraints limit the ways something can be used, preventing misuse.

In API design:

Affordance is achieved through types, names, and structure that guide correct usage
Constraints are achieved through type systems, validation, and design choices that prevent misuse

Good APIs make correct usage obvious and incorrect usage impossible (or at least difficult).

AffordanceAndConstraints.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
// ❌ No constraints: Misuse is easy
function sendEmail(
    to: string,       // Any string? What format?
    subject: string,  // Any length?
    body: string,     // Plain text? HTML?
    options: object   // Any properties?
): void { /* ... */ }
 
// Easy to call incorrectly:
sendEmail("not-an-email", "", "", { invalid: true });
 
// ✅ Affordances and constraints guide correct usage
// Branded types as constraints
type EmailAddress = string & { readonly __brand: 'EmailAddress' };
type NonEmptyString = string & { readonly __brand: 'NonEmpty' };
 
// Factory functions afford correct construction
function toEmailAddress(s: string): EmailAddress {
    if (!isValidEmail(s)) {
        throw new InvalidEmailError(s);
    }
    return s as EmailAddress;
}
 
// Structured options afford discovery
interface EmailOptions {
    format: 'text' | 'html';             // Constrained choices
    priority: 'low' | 'normal' | 'high'; // Constrained choices
    attachments?: Attachment[];           // Optional with clear type
}
 
// Better signature affords correct usage
function sendEmail(
    to: EmailAddress,         // Type constraints email format
    subject: NonEmptyString,  // Type constraints non-empty
    body: EmailContent,       // Union type for text/html variants
    options: EmailOptions     // Structured options
): Promise<EmailResult> { /* ... */ }
 
// Misuse becomes difficult:
// sendEmail("not-email", "", "", {});  // Compile errors!
 
// Correct usage is guided:
const email = toEmailAddress('user@example.com');
const subject = nonEmpty('Your order shipped!');
await sendEmail(email, subject, textContent('...'), {
    format: 'text',
    priority: 'normal'
});

Type-Level Affordances:

Modern type systems offer powerful tools for building affordance into APIs:

Type-Level Design Patterns

•Union types: Constrain parameters to valid options ('asc' | 'desc' instead of string)
•Branded/phantom types: Encode validation state in types (EmailAddress instead of string)
•Literal types: Accept only specific values (1 | 2 | 3 instead of number)
•Template literal types: Encode format patterns (\user-${string}`` for prefixed IDs)
•Discriminated unions: Make invalid states unrepresentable ({ type: 'success', data } | { type: 'error', message })
•Builder patterns: Guide complex construction step-by-step with type-safe transitions

Making Invalid States Unrepresentable:

The gold standard for API design is making it impossible to represent invalid states. If your types prevent invalid inputs from existing, you don't need runtime validation or error handling for those cases.

InvalidStatesUnrepresentable.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
// ❌ Invalid states are representable
interface ShippingInfo {
    method: 'standard' | 'express' | 'pickup';
    address?: Address;    // Required for standard/express, forbidden for pickup
    pickupLocation?: string;  // Required for pickup, forbidden for standard/express
}
 
// This compiles but is invalid:
const invalid1: ShippingInfo = {
    method: 'standard',
    // Missing address!
};
 
const invalid2: ShippingInfo = {
    method: 'pickup',
    address: someAddress,  // Shouldn't have address!
};
 
// ✅ Invalid states are unrepresentable
type ShippingInfo =
    | { method: 'standard'; address: Address }
    | { method: 'express'; address: Address }
    | { method: 'pickup'; pickupLocation: string };
 
// Now invalid states won't compile:
// { method: 'standard' }  // Error: missing 'address'
// { method: 'pickup', address: someAddress }  // Error: object literal...
 
// Only valid combinations are possible:
const valid1: ShippingInfo = { method: 'standard', address: homeAddress };
const valid2: ShippingInfo = { method: 'pickup', pickupLocation: 'Store #42' };

Design to the Type System's Strengths

Different programming languages have different type system capabilities. Design your API to leverage what your type system can express. In TypeScript, use discriminated unions; in Rust, use enums; in Java, use sealed classes. Push as much correctness as possible into compile-time checks.

Error Usability

Error handling is a critical part of API usability. When things go wrong—and they will—how your API communicates failure determines whether developers can diagnose and fix issues quickly.

Hallmarks of usable error design:

Error Usability Principles

•Specific error types: Different failure modes should have different error types that developers can catch and handle separately
•Clear error messages: Messages should explain what went wrong, why it went wrong, and ideally how to fix it
•Structured error data: Include machine-readable error codes, field paths for validation errors, and any context needed for debugging
•Consistent error format: All errors across the API should follow the same structure
•Actionable guidance: Errors should tell developers what to do next, not just what failed
•No silent failures: Never swallow errors or return success when something went wrong

ErrorUsability.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
// ❌ Unusable errors
throw new Error('Invalid input'); // What input? How is it invalid?
throw new Error('Not found');     // What wasn't found?
throw new Error('Failed');        // What failed? Why? Retry?
 
// ✅ Usable errors with full context
class ValidationError extends Error {
    constructor(
        public readonly field: string,
        public readonly constraint: string,
        public readonly value: unknown,
        public readonly suggestion?: string
    ) {
        super(
            `Validation failed for '${field}': ${constraint}. ` +
                                        `Received: ${JSON.stringify(value)}.` +
            (suggestion ? ` ${suggestion}` : '')
        );
        this.name = 'ValidationError';
    }
}
 
throw new ValidationError(
    'email',
    'must be a valid email address',
    'not-an-email',
    'Email addresses must contain @ and a domain, e.g., user@example.com'
);
 
// Error output:
// ValidationError: Validation failed for 'email': must be a valid email address.
// Received: "not-an-email". Email addresses must contain @ and a domain,
// e.g., user@example.com
 
// For REST APIs, structured error responses:
interface ApiErrorResponse {
    error: {
        code: string;           // Machine-readable: 'VALIDATION_ERROR'
        message: string;        // Human-readable summary
        details?: {             // Specific issues
            field: string;      // Which field failed
            constraint: string; // What rule was violated
            value?: unknown;    // What was provided (if safe to log)
        }[];
        requestId: string;      // For support/debugging
        documentation?: string; // Link to relevant docs
    };
}
 
// Example response:
{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "The request contains invalid parameters",
        "details": [
            {
                "field": "email",
                "constraint": "must be a valid email address",
                "value": "not-an-email"
            },
            {
                "field": "age",
                "constraint": "must be a positive integer",
                "value": -5
            }
        ],
        "requestId": "req_1234567890",
        "documentation": "https://api.example.com/docs/errors#VALIDATION_ERROR"
    }
}

The Error Test

For every error your API can produce, ask: 'If a developer sees this at 2 AM, can they fix the problem without digging through source code?' If not, improve the error message. Include the context they'll need: which parameter failed, what value was provided, what was expected, and what they should do next.

Summary: Usability Principles

We've explored the usability principles that transform technically correct APIs into APIs that developers genuinely enjoy using. These principles aren't luxuries—they're the difference between APIs that gain adoption and those that developers avoid.

Let's consolidate the key insights:

Key Takeaways

•Principle of Least Astonishment: APIs should behave as developers expect. Analyze expectations from language, domain, API, and computing conventions.
•Discoverability: Design APIs that teach themselves through names, types, and structure. Leverage IDE tooling through rich type information.
•Progressive Disclosure: Make simple things simple and complex things possible. Use sensible defaults, layered APIs, and optional advanced features.
•Simplicity: Reduce cognitive load through single-responsibility methods, minimal parameters, and predictable patterns. Avoid cleverness that sacrifices clarity.
•Consistency: Apply the same patterns throughout your API, align with platform conventions, and maintain patterns across versions.
•Affordance and Constraints: Use types and structure to guide correct usage and prevent misuse. Make invalid states unrepresentable when possible.
•Error Usability: Design errors that explain what went wrong, why, and how to fix it. Use structured errors with machine-readable codes and human-readable messages.

What's Next:

While usability principles describe how each interaction should feel, consistency deserves deeper exploration. The next page focuses specifically on consistency—how to achieve it systematically, common consistency anti-patterns, and how to maintain consistency as APIs evolve over time.

Page Complete

You now understand the usability principles that make APIs intuitive and pleasant to use. These principles work together: consistency enables the Principle of Least Astonishment, discoverability enables progressive disclosure, and clear affordances reduce the need for error handling. Apply them holistically for maximum impact.

2 / 4

Loading learning content...

System Design (LLD)API & Interface Design

What Is a Good API?

LevelIntermediate

Duration60 mins

TopicAPI & Interface Design

2 / 4

Usability Principles

Beyond Correctness: The Art of Usable APIs

What You Will Learn

The Principle of Least Astonishment

The Principle of Least Astonishment (POLA), also called the Principle of Least Surprise, is perhaps the most fundamental usability principle in API design:

An API should behave the way users expect it to behave.

Astonishment creates cognitive friction:

Common Sources of API Surprise

•Unexpected return values: array.sort() modifies in-place AND returns the array (which one am I supposed to use?)
•Inconsistent parameter ordering: substring(start, end) vs slice(start, length) vs substr(start, length)
•Silent failures: Operation succeeds but does nothing because of an undocumented precondition
•Side effects in getters: getValue() that modifies internal state
•Asymmetric operations: add() that takes an object, but remove() that takes an ID
•Type coercion surprises: JavaScript's '5' + 3 = '53' but '5' - 3 = 2
•Unusual defaults: A creation operation that automatically publishes, or a delete that's permanent without warning

Analyzing Expectations:

To apply POLA, you must understand where expectations come from:

Language conventions: What do similar operations typically do in this programming language?
Domain conventions: What do similar operations mean in this problem domain?
API conventions: What patterns have you established elsewhere in this API?
General computing conventions: What do developers generally expect from operations like "get," "create," "delete," "update"?

When multiple conventions conflict, prefer the convention closest to the user's mental model—typically domain conventions for domain operations, and computing conventions for technical operations.

LeastAstonishmentExamples.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
// ❌ Astonishing: Non-intuitive behavior
class OrderService {
    // Returns null on success, error message on failure
    // Why would success return null? Unexpected!
    createOrder(items: Item[]): string | null { /* ... */ }
    
    // Updates and deletes always succeed (even if entity didn't exist)
    // User can't tell if their intent was fulfilled
    updateOrder(id: string, updates: Partial<Order>): void { /* ... */ }
    
    // Returns the number of items, but modifies the cart (!)
    // Getter with side effect - extremely surprising
    getItemCount(): number { 
        this.lastAccessTime = Date.now(); // Hidden side effect!
        return this.items.length;
    }
}
 
// ✅ Unsurprising: Intuitive behavior
class OrderService {
    // Returns the created order on success, throws on failure
    // Standard pattern that developers expect
    createOrder(items: Item[]): Order { /* ... */ }
    
    // Returns the updated order, throws if order doesn't exist
    // User knows their intent was fulfilled or why it wasn't
    updateOrder(id: string, updates: Partial<Order>): Order { /* ... */ }
    
    // Pure getter with no side effects
    getItemCount(): number { 
        return this.items.length; 
    }
    
    // Explicit method for recording access (if needed)
    recordAccess(): void {
        this.lastAccessTime = Date.now();
    }
}

Testing for Astonishment

Discoverability: Self-Explaining APIs

Why discoverability matters:

Reduces time to first success
Lowers learning curve
Improves developer experience and satisfaction
Reduces support burden
Enables IDE-driven exploration (autocomplete, type hints)

Principles of discoverable design:

Elements of Discoverability

•Intention-revealing names: Method names should express what they do, not how. calculateShippingCost() not runShippingAlgorithm()
•Consistent vocabulary: Use the same term for the same concept. Don't switch between 'user', 'account', 'member', and 'profile' randomly
•Logical grouping: Related operations should be co-located. All user operations on UserService, not scattered across the codebase
•Progressive complexity: Start with simple, common operations that suggest more advanced options
•Meaningful return types: Return types should suggest what you can do next
•Rich type information: Types that enable IDE autocomplete, code navigation, and inline documentation

Names as Documentation:

Good names are the first line of documentation. They should be:

Naming Quality Criteria
Quality	Description	Poor Example	Better Example
Specific	Names should convey precise meaning	process()	validatePaymentMethod()
Unambiguous	Only one reasonable interpretation	handleData()	persistUserProfile()
Consistent	Similar patterns for similar operations	getUser() / fetchOrder()	getUser() / getOrder()
Pronounceable	Can be spoken aloud in discussion	procUsrRcrd()	processUserRecord()
Searchable	Easy to find via text search	x, tmp, data	orderTotal, tempFilePath
Domain-aligned	Uses language of the business domain	updateFlag()	activateSubscription()

The Fluent Interface Pattern:

Fluent interfaces maximize discoverability by making the next possible action obvious through method chaining:

FluentInterface.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// Fluent interface: Each return type suggests the next action
const query = db.users()
    .where('active', true)            // Returns ConditionBuilder
    .orderBy('createdAt', 'desc')     // Returns SortBuilder
    .limit(10)                        // Returns Limiter
    .select('id', 'name', 'email')    // Returns SelectBuilder
    .execute();                        // Returns Promise<User[]>
 
// The type system guides discovery:
// After .where(), IDE suggests: and(), or(), orderBy(), limit(), select()
// After .orderBy(), IDE suggests: thenBy(), limit(), select()
// After .limit(), IDE suggests: offset(), select(), execute()
// After .select(), IDE suggests: execute()
 
// Each step narrows possibilities, guiding developers through the API
 
// The Builder Pattern enables discoverability for complex object construction:
const notification = NotificationBuilder
    .create()
    .to('user@example.com')
    .withSubject('Your order shipped!')
    .withBody('Track your package at...')
    .withPriority('high')
    .schedule(tomorrow)
    .build();
    
// Without builder, developers would face:
// new Notification(to, subject, body, null, null, priority, null, schedule, ...)

IDE as Partner

Progressive Disclosure

Progressive disclosure is a design principle borrowed from user interface design: reveal complexity gradually, showing simple options first and exposing advanced options only when needed.

APIs often fail by either:

Overwhelming beginners: Exposing every option upfront, making simple tasks feel complex
Handicapping experts: Hiding advanced capabilities so deeply that power users can't access them

Progressive disclosure solves both: make simple things simple, and complex things possible.

No Progressive Disclosure

•10 required parameters for basic operation
•Must understand entire config before starting
•Advanced and common options mixed together
•Can't do simple things simply

With Progressive Disclosure

•1-2 parameters for basic operation
•Sensible defaults for common cases
•Advanced options on specialized types
•Simple and complex each have a clean path

Implementation Strategies:

1. Sensible Defaults:

Every optional parameter should have a sensible default. The 80% use case should require minimal configuration.

SensibleDefaults.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
// ❌ No defaults: Every option required
function createHttpClient(
    baseUrl: string,
    timeout: number,
    retries: number,
    retryDelay: number,
    headers: Record<string, string>,
    interceptors: Interceptor[],
    cacheConfig: CacheConfig,
    certificateValidation: boolean,
    followRedirects: boolean,
    maxRedirects: number
): HttpClient { /* ... */ }
 
// Usage requires understanding everything:
const client = createHttpClient(
    'https://api.example.com',
    30000,    // What's a good timeout?
    3,        // How many retries?
    1000,     // What delay? Exponential?
    {},       // Any headers?
    [],       // Interceptors?
    ???,      // What's CacheConfig?
    true,     // Why would I not validate?
    true,     // Why would I not follow redirects?
    10        // 10 redirects?
);
 
// ✅ Progressive disclosure with smart defaults
interface HttpClientOptions {
    timeout?: number;          // Default: 30000ms
    retries?: number;          // Default: 3
    retryDelay?: number;       // Default: 1000ms with exponential backoff
    headers?: Record<string, string>;
    interceptors?: Interceptor[];
    cache?: CacheConfig | boolean; // true = default caching
    validateCertificates?: boolean; // Default: true
    followRedirects?: boolean | number; // true = follow (max 10)
}
 
function createHttpClient(
    baseUrl: string,
    options: HttpClientOptions = {}
): HttpClient { /* ... */ }
 
// Simple use case: just works
const simple = createHttpClient('https://api.example.com');
 
// Customized use case: override what you need
const custom = createHttpClient('https://api.example.com', {
    timeout: 60000,
    retries: 5
});
 
// Advanced use case: full control available
const advanced = createHttpClient('https://api.example.com', {
    timeout: 60000,
    retries: 5,
    retryDelay: 500,
    headers: { 'X-Custom-Header': 'value' },
    interceptors: [loggingInterceptor, authInterceptor],
    cache: { maxAge: 3600, staleWhileRevalidate: true },
    validateCertificates: false, // Explicit dev override
    followRedirects: 5
});

2. Layered APIs:

Provide multiple entry points at different abstraction levels:

LayeredApiDesign.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// Layer 1: High-level convenience methods (80% of users)
class FileStorage {
    // Simple: upload a file, get a URL
    async uploadFile(file: File): Promise<string> {
        return this.uploadWithOptions(file, {});
    }
}
 
// Layer 2: Configurable methods (15% of users)
class FileStorage {
    async uploadWithOptions(file: File, options: UploadOptions): Promise<UploadResult> {
        const request = this.buildUploadRequest(file, options);
        return this.executeRequest(request);
    }
}
 
// Layer 3: Full control (5% of users - library authors, power users)
class FileStorage {
    buildUploadRequest(file: File, options: UploadOptions): UploadRequest { 
        /* ... */ 
    }
    
    async executeRequest(request: UploadRequest): Promise<UploadResult> {
        /* ... */
    }
    
    // Full access to underlying client
    getStorageClient(): StorageClient { /* ... */ }
}

The Rule of Three Levels

Simplicity: Reducing Cognitive Load

Cognitive load in API usage:

Simplification strategies:

Strategies for Simplicity

•Single responsibility per method: Each method does one thing well. Avoid multi-purpose Swiss Army knife methods.
•Minimal parameter counts: Fewer parameters mean fewer decisions. Aim for 0-3 required parameters.
•Obvious parameter order: When multiple parameters are needed, order them intuitively (subject before predicate, source before destination).
•Orthogonal concepts: Each concept should be independent. Learning one doesn't require understanding another.
•No hidden modes: Behavior shouldn't depend on invisible state. Each call should be understandable in isolation.
•Predictable patterns: Once developers learn a pattern, it should apply everywhere in the API.

The Cost of Clever:

SimpleVsClever.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
// ❌ Clever: Operator overloading and fluent DSL
const results = users
    | where(u => u.active > true)   // Custom | operator
    << order('name')                 // Custom << operator
    >> take(10);                     // Custom >> operator
    
// Looks elegant, but:
// - Requires learning custom operators
// - Breaks tooling expectations
// - Hard to debug (what does | actually do?)
// - Unfamiliar to new developers
 
// ✅ Simple: Standard method calls with obvious names
const results = users
    .where(u => u.active === true)
    .orderBy('name')
    .take(10);
 
// Instantly familiar:
// - Standard method chaining
// - Clear method names
// - Debuggable step-by-step
// - Obvious to any JavaScript/TypeScript developer
 
// ❌ Clever: Magic string parameters
db.query('users', 'active:true,role:admin', 'name,-createdAt');
 
// What do these strings mean? Users must check documentation
 
// ✅ Simple: Structured parameters with types
db.query({
    table: 'users',
    where: { active: true, role: 'admin' },
    orderBy: [
        { field: 'name', direction: 'asc' },
        { field: 'createdAt', direction: 'desc' }
    ]
});
 
// Self-documenting, type-checked, IDE-friendly

Complexity Budget:

Every API has a complexity budget. Some complexity is unavoidable—the domain itself may be complex. The question is where to spend that budget.

Spend complexity on domain problems: If the problem domain is genuinely complex, it's acceptable for the API to reflect that complexity.
Don't spend complexity on API mechanics: The overhead of using your API should be minimal. Protocol, authentication, error handling, and serialization should be simple.
Make the common case cheap, the advanced case possible: Developers doing common tasks shouldn't pay the cognitive cost of advanced features they're not using.

Simple ≠ Simplistic

Consistency: Patterns That Transfer

Consistency operates at multiple levels:

1. Internal Consistency (within your API):

All operations in your API should follow the same patterns:

InternalConsistency.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
// ❌ Inconsistent: Every resource uses different patterns
interface InconsistentApi {
    // Users: CRUD with objects
    createUser(data: UserData): User;
    getUser(id: string): User | null;
    updateUser(id: string, data: Partial<UserData>): User;
    deleteUser(id: string): void;
    
    // Orders: Different naming, different patterns
    newOrder(items: Item[]): Order;           // Why 'new' not 'create'?
    fetchOrder(orderId: number): Order;       // Why 'fetch' not 'get'? Why number not string?
    modifyOrder(order: Order): Order;         // Why pass full object not ID?
    removeOrder(id: string): boolean;         // Why return boolean not void?
    
    // Products: Yet another pattern
    addProduct(name: string, price: number): string;  // Returns ID, not object?
    product(id: string): Promise<Product>;    // Async when others aren't?
    // No update method?
    deleteProduct(id: number): void;          // ID is number now?
}
 
// ✅ Consistent: Unified patterns across all resources
interface ConsistentApi {
    // All resources follow the same pattern
    createUser(data: UserData): User;
    getUser(id: string): User | null;
    updateUser(id: string, data: Partial<UserData>): User;
    deleteUser(id: string): void;
    listUsers(query?: QueryOptions): User[];
    
    createOrder(data: OrderData): Order;
    getOrder(id: string): Order | null;
    updateOrder(id: string, data: Partial<OrderData>): Order;
    deleteOrder(id: string): void;
    listOrders(query?: QueryOptions): Order[];
    
    createProduct(data: ProductData): Product;
    getProduct(id: string): Product | null;
    updateProduct(id: string, data: Partial<ProductData>): Product;
    deleteProduct(id: string): void;
    listProducts(query?: QueryOptions): Product[];
}
 
// Now learning one resource teaches you all resources

2. External Consistency (with platform conventions):

Your API should align with conventions developers already know:

Platform Conventions to Respect
Convention Source	Examples to Follow	Violation Impact
Language idioms	JavaScript uses camelCase, Python uses snake_case	Feels foreign, triggers constant mental translation
Ecosystem standards	HTTP libraries return Response objects with status, headers, body	Breaks expectations from other libraries
Framework patterns	Express middleware signature: (req, res, next)	Developers struggle to integrate
Popular APIs	Stripe's resource.action() pattern	Misses opportunity to leverage existing knowledge

3. Temporal Consistency (across versions):

Patterns should remain consistent across versions of your API. Introducing new patterns in new versions fractures the developer's mental model and complicates codebases that use multiple versions.

The Consistency Checklist:

Applying Consistency Systematically

•Naming patterns: If one resource uses getUser(), all resources should use get{Resource}(), not fetch{Resource}() or find{Resource}()
•Parameter patterns: If one method takes (id, data), similar methods should use the same order
•Return patterns: If one method returns Entity | null, similar methods shouldn't throw NotFoundException
•Error patterns: Consistent error types, codes, and messages across all operations
•Async patterns: If some operations are async, similar operations should be async too
•Null/undefined patterns: Consistent treatment of missing values throughout the API

The Consistency Tax

Affordance and Constraints

In API design:

Affordance is achieved through types, names, and structure that guide correct usage
Constraints are achieved through type systems, validation, and design choices that prevent misuse

Good APIs make correct usage obvious and incorrect usage impossible (or at least difficult).

AffordanceAndConstraints.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
// ❌ No constraints: Misuse is easy
function sendEmail(
    to: string,       // Any string? What format?
    subject: string,  // Any length?
    body: string,     // Plain text? HTML?
    options: object   // Any properties?
): void { /* ... */ }
 
// Easy to call incorrectly:
sendEmail("not-an-email", "", "", { invalid: true });
 
// ✅ Affordances and constraints guide correct usage
// Branded types as constraints
type EmailAddress = string & { readonly __brand: 'EmailAddress' };
type NonEmptyString = string & { readonly __brand: 'NonEmpty' };
 
// Factory functions afford correct construction
function toEmailAddress(s: string): EmailAddress {
    if (!isValidEmail(s)) {
        throw new InvalidEmailError(s);
    }
    return s as EmailAddress;
}
 
// Structured options afford discovery
interface EmailOptions {
    format: 'text' | 'html';             // Constrained choices
    priority: 'low' | 'normal' | 'high'; // Constrained choices
    attachments?: Attachment[];           // Optional with clear type
}
 
// Better signature affords correct usage
function sendEmail(
    to: EmailAddress,         // Type constraints email format
    subject: NonEmptyString,  // Type constraints non-empty
    body: EmailContent,       // Union type for text/html variants
    options: EmailOptions     // Structured options
): Promise<EmailResult> { /* ... */ }
 
// Misuse becomes difficult:
// sendEmail("not-email", "", "", {});  // Compile errors!
 
// Correct usage is guided:
const email = toEmailAddress('user@example.com');
const subject = nonEmpty('Your order shipped!');
await sendEmail(email, subject, textContent('...'), {
    format: 'text',
    priority: 'normal'
});

Type-Level Affordances:

Modern type systems offer powerful tools for building affordance into APIs:

Type-Level Design Patterns

•Union types: Constrain parameters to valid options ('asc' | 'desc' instead of string)
•Branded/phantom types: Encode validation state in types (EmailAddress instead of string)
•Literal types: Accept only specific values (1 | 2 | 3 instead of number)
•Template literal types: Encode format patterns (\user-${string}`` for prefixed IDs)
•Discriminated unions: Make invalid states unrepresentable ({ type: 'success', data } | { type: 'error', message })
•Builder patterns: Guide complex construction step-by-step with type-safe transitions

Making Invalid States Unrepresentable:

InvalidStatesUnrepresentable.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
// ❌ Invalid states are representable
interface ShippingInfo {
    method: 'standard' | 'express' | 'pickup';
    address?: Address;    // Required for standard/express, forbidden for pickup
    pickupLocation?: string;  // Required for pickup, forbidden for standard/express
}
 
// This compiles but is invalid:
const invalid1: ShippingInfo = {
    method: 'standard',
    // Missing address!
};
 
const invalid2: ShippingInfo = {
    method: 'pickup',
    address: someAddress,  // Shouldn't have address!
};
 
// ✅ Invalid states are unrepresentable
type ShippingInfo =
    | { method: 'standard'; address: Address }
    | { method: 'express'; address: Address }
    | { method: 'pickup'; pickupLocation: string };
 
// Now invalid states won't compile:
// { method: 'standard' }  // Error: missing 'address'
// { method: 'pickup', address: someAddress }  // Error: object literal...
 
// Only valid combinations are possible:
const valid1: ShippingInfo = { method: 'standard', address: homeAddress };
const valid2: ShippingInfo = { method: 'pickup', pickupLocation: 'Store #42' };

Design to the Type System's Strengths

Error Usability

Error handling is a critical part of API usability. When things go wrong—and they will—how your API communicates failure determines whether developers can diagnose and fix issues quickly.

Hallmarks of usable error design:

Error Usability Principles

•Specific error types: Different failure modes should have different error types that developers can catch and handle separately
•Clear error messages: Messages should explain what went wrong, why it went wrong, and ideally how to fix it
•Structured error data: Include machine-readable error codes, field paths for validation errors, and any context needed for debugging
•Consistent error format: All errors across the API should follow the same structure
•Actionable guidance: Errors should tell developers what to do next, not just what failed
•No silent failures: Never swallow errors or return success when something went wrong

ErrorUsability.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
// ❌ Unusable errors
throw new Error('Invalid input'); // What input? How is it invalid?
throw new Error('Not found');     // What wasn't found?
throw new Error('Failed');        // What failed? Why? Retry?
 
// ✅ Usable errors with full context
class ValidationError extends Error {
    constructor(
        public readonly field: string,
        public readonly constraint: string,
        public readonly value: unknown,
        public readonly suggestion?: string
    ) {
        super(
            `Validation failed for '${field}': ${constraint}. ` +
                                        `Received: ${JSON.stringify(value)}.` +
            (suggestion ? ` ${suggestion}` : '')
        );
        this.name = 'ValidationError';
    }
}
 
throw new ValidationError(
    'email',
    'must be a valid email address',
    'not-an-email',
    'Email addresses must contain @ and a domain, e.g., user@example.com'
);
 
// Error output:
// ValidationError: Validation failed for 'email': must be a valid email address.
// Received: "not-an-email". Email addresses must contain @ and a domain,
// e.g., user@example.com
 
// For REST APIs, structured error responses:
interface ApiErrorResponse {
    error: {
        code: string;           // Machine-readable: 'VALIDATION_ERROR'
        message: string;        // Human-readable summary
        details?: {             // Specific issues
            field: string;      // Which field failed
            constraint: string; // What rule was violated
            value?: unknown;    // What was provided (if safe to log)
        }[];
        requestId: string;      // For support/debugging
        documentation?: string; // Link to relevant docs
    };
}
 
// Example response:
{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "The request contains invalid parameters",
        "details": [
            {
                "field": "email",
                "constraint": "must be a valid email address",
                "value": "not-an-email"
            },
            {
                "field": "age",
                "constraint": "must be a positive integer",
                "value": -5
            }
        ],
        "requestId": "req_1234567890",
        "documentation": "https://api.example.com/docs/errors#VALIDATION_ERROR"
    }
}

The Error Test

Summary: Usability Principles

Let's consolidate the key insights:

Key Takeaways

•Principle of Least Astonishment: APIs should behave as developers expect. Analyze expectations from language, domain, API, and computing conventions.
•Discoverability: Design APIs that teach themselves through names, types, and structure. Leverage IDE tooling through rich type information.
•Progressive Disclosure: Make simple things simple and complex things possible. Use sensible defaults, layered APIs, and optional advanced features.
•Simplicity: Reduce cognitive load through single-responsibility methods, minimal parameters, and predictable patterns. Avoid cleverness that sacrifices clarity.
•Consistency: Apply the same patterns throughout your API, align with platform conventions, and maintain patterns across versions.
•Affordance and Constraints: Use types and structure to guide correct usage and prevent misuse. Make invalid states unrepresentable when possible.
•Error Usability: Design errors that explain what went wrong, why, and how to fix it. Use structured errors with machine-readable codes and human-readable messages.

What's Next:

Page Complete

2 / 4