System Design (LLD)API & Interface Design

What Is a Good API?

LevelIntermediate

Duration60 mins

TopicAPI & Interface Design

3 / 4

Consistency in API Design

The Multiplier Effect of Consistency

When you learn one part of a well-designed API, you've essentially learned them all. The patterns you discover in one area apply everywhere else. This is the power of consistency—it transforms an API surface from a collection of independent features into a cohesive system where knowledge compounds.

Inconsistent APIs, by contrast, force developers to relearn patterns for each new area. Every operation becomes a special case. The cognitive burden accumulates until the API feels hostile and unpredictable. Developers lose confidence: if the API is inconsistent here, they wonder, what other surprises await?

Consistency is perhaps the most impactful investment you can make in API design. This page explores consistency in depth: what dimensions require consistency, how to achieve it systematically, and how to maintain it as your API evolves.

What You Will Learn

By the end of this page, you will understand: (1) The multiple dimensions of API consistency—naming, structural, behavioral, and semantic; (2) How to establish and enforce consistency conventions; (3) Common consistency anti-patterns and how to avoid them; (4) Strategies for maintaining consistency across teams and over time; and (5) When consistency might be appropriately violated.

Dimensions of Consistency

Consistency isn't a single property—it spans multiple dimensions that together create a unified developer experience.

1. Naming Consistency:

Names are the first thing developers encounter. Consistent naming means:

Naming Consistency Elements

•Vocabulary consistency: The same word means the same thing everywhere (user, never account/member/profile interchangeably)
•Grammatical consistency: Same parts of speech for same concepts (verbs for actions: get, create, delete)
•Casing consistency: Uniform casing convention (camelCase, snake_case, PascalCase) throughout
•Abbreviation consistency: Either always abbreviate or never (not getUserId + getUsrEmail)
•Pluralization consistency: Consistent handling of collections (users vs user_list vs userArray)

2. Structural Consistency:

The shape and organization of API elements should follow predictable patterns:

Structural Consistency Elements

•Parameter order: Consistent ordering (e.g., required before optional, resource ID before data)
•Return type patterns: Similar operations return similar structures
•Request/response shapes: Consistent envelope structure, pagination patterns, metadata placement
•Hierarchy organization: Predictable nesting and grouping of related operations
•Configuration patterns: Same approach to options objects, defaults, and overrides

3. Behavioral Consistency:

How operations behave should be predictable:

Behavioral Consistency Elements

•Error handling patterns: Same error types, codes, and messages for equivalent situations
•Null handling: Consistent treatment (return null, throw, return empty collection)
•Side effect patterns: Equivalent operations have equivalent side effects
•Async patterns: Consistent use of callbacks, promises, or async/await
•Idempotency: Consistent retry-safety behavior for similar operations

4. Semantic Consistency:

The meaning of operations and concepts should be stable:

Semantic Consistency Elements

•Operation semantics: delete always means the same thing (soft delete? hard delete? archival?)
•Field semantics: createdAt always means the same thing with the same format
•Status semantics: active means the same thing for users, orders, subscriptions
•Relationship semantics: Parent-child, ownership, and reference relationships work the same way

Consistency Establishes Expectations

Every consistent pattern teaches developers what to expect. Every inconsistency forces them to stop, check documentation, and adjust their mental model. Multiply this across an entire API, and consistency (or its absence) dramatically impacts productivity.

Naming Convention Systems

Establishing a systematic naming convention is the foundation of API consistency. A well-designed naming system makes the right name obvious and wrong names stand out.

Building a Naming Convention:

1. Choose a Vocabulary:

Decide on standard terms for common concepts:

Example Vocabulary Standardization
Concept	Standard Term	Rejected Alternatives
Fetch a resource	get	fetch, retrieve, find, load, read
Create a resource	create	add, new, make, insert, post
Update a resource	update	modify, change, edit, patch, set
Remove a resource	delete	remove, destroy, drop, erase
Collection of items	list	getAll, findAll, query, fetch, index
Entity identifier	id	identifier, key, uid, guid

2. Define Naming Patterns:

Create templates for common operations:

NamingPatterns.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
// Naming pattern templates
// For service methods:
 
// CRUD operations: {verb}{Resource}
getUser(id: string): User
createUser(data: UserData): User
updateUser(id: string, data: Partial<UserData>): User
deleteUser(id: string): void
 
// Collection operations: list{Resources}
listUsers(query?: QueryOptions): User[]
listOrders(query?: QueryOptions): Order[]
 
// Relationship operations: {verb}{Resource}{Relationship}
getUserOrders(userId: string): Order[]
getOrderItems(orderId: string): Item[]
 
// Status changes: {verb}{Resource} where verb indicates target state
activateUser(id: string): User
deactivateUser(id: string): User
publishPost(id: string): Post
archivePost(id: string): Post
 
// Check operations: is{Condition} or has{Property} or can{Action}
isUserActive(id: string): boolean
hasUserPermission(userId: string, permission: string): boolean
canUserPerformAction(userId: string, action: string): boolean
 
// Batch operations: {verb}{Resources} (plural)
createUsers(data: UserData[]): User[]
deleteUsers(ids: string[]): void
 
// Search operations: search{Resources} or find{Resources}By{Criteria}
searchUsers(query: string): User[]
findUsersByRole(role: string): User[]

3. Establish Grammatical Rules:

Grammatical Consistency Rules

•Methods are verbs or verb phrases: getUser, validatePayment, processOrder
•Types and classes are nouns: User, PaymentProcessor, OrderService
•Boolean methods/properties start with is/has/can: isValid, hasPermission, canDelete
•Factory methods use create or build: createOrder, buildRequest
•Conversion methods use to or as: toJSON, asString, toDTO
•Event handlers use on or handle: onUserCreated, handleOrderPlaced

4. Casing Conventions:

Casing by Element Type
Element	Convention	Example
Variables and parameters	camelCase	userId, orderTotal
Methods and functions	camelCase	getUser, calculateTotal
Classes and types	PascalCase	UserService, OrderItem
Constants	SCREAMING_SNAKE_CASE	MAX_RETRY_COUNT
Enum values	SCREAMING_SNAKE_CASE or PascalCase	ORDER_STATUS.PENDING
JSON keys (REST)	camelCase or snake_case (pick one)	{ userId: 123 }

Document Your Conventions

Create an API style guide that documents your naming conventions with examples. Make it mandatory reading for any contributor. Better yet, create automated linters that enforce your conventions—humans forget, but machines don't.

Structural Patterns

Beyond naming, the structural organization of your API must follow consistent patterns. Developers should be able to predict structure before they see documentation.

Parameter Ordering:

Establish a standard parameter order and apply it everywhere:

ParameterOrdering.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// Standard parameter ordering convention:
// 1. Target/Subject identifier (what we're operating on)
// 2. Data/Payload (what we're providing)
// 3. Options (how to perform the operation)
 
// ✅ Consistent ordering across all methods
updateUser(userId: string, data: Partial<User>, options?: UpdateOptions): User
updateOrder(orderId: string, data: Partial<Order>, options?: UpdateOptions): Order
updateProduct(productId: string, data: Partial<Product>, options?: UpdateOptions): Product
 
// ❌ Inconsistent ordering - breaks expectations
updateUser(userId: string, data: Partial<User>): User
updateOrder(data: Partial<Order>, orderId: string): Order  // Why is order different?
updateProduct(options: UpdateOptions, productId: string, data: Partial<Product>): Product  // ?!
 
// Callback positioning: always last (convention in most languages)
fetchData(url: string, options: FetchOptions, callback: Callback): void
 
// Promise-based methods: no callback parameter
fetchData(url: string, options?: FetchOptions): Promise<Response>

Options Object Patterns:

When methods need many optional parameters, use options objects with consistent structure:

OptionsPatterns.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
// Common options structure across all list operations
interface ListOptions {
    // Pagination (same shape everywhere)
    limit?: number;
    offset?: number;
    cursor?: string;
    
    // Filtering (consistent pattern)
    filter?: Record<string, unknown>;
    
    // Sorting (consistent pattern)
    orderBy?: string | { field: string; direction: 'asc' | 'desc' }[];
    
    // Field selection (consistent pattern)
    fields?: string[];
    
    // Expansion (consistent pattern)
    expand?: string[];
}
 
// All list methods accept the same options shape
listUsers(options?: ListOptions): Promise<PaginatedResult<User>>
listOrders(options?: ListOptions): Promise<PaginatedResult<Order>>
listProducts(options?: ListOptions): Promise<PaginatedResult<Product>>
 
// Response structure is also consistent
interface PaginatedResult<T> {
    data: T[];
    pagination: {
        total: number;
        limit: number;
        offset: number;
        hasMore: boolean;
        nextCursor?: string;
    };
    metadata?: {
        executionTimeMs: number;
    };
}

Response Envelope Patterns:

For REST APIs and similar interfaces, consistent response envelopes eliminate guesswork:

ResponseEnvelopes.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
// Consistent response envelopes
 
// Single resource response
interface SingleResponse<T> {
    data: T;
    meta?: {
        requestId: string;
        timestamp: string;
    };
}
 
// Collection response
interface CollectionResponse<T> {
    data: T[];
    pagination: PaginationInfo;
    meta?: {
        requestId: string;
        timestamp: string;
        totalCount: number;
    };
}
 
// Error response
interface ErrorResponse {
    error: {
        code: string;
        message: string;
        details?: ValidationError[] | Record<string, unknown>;
        requestId: string;
        timestamp: string;
    };
}
 
// All endpoints follow the same pattern:
// GET /users/:id     -> SingleResponse<User>
// GET /users         -> CollectionResponse<User>
// POST /users        -> SingleResponse<User>
// PATCH /users/:id   -> SingleResponse<User>
// DELETE /users/:id  -> { meta: { requestId, timestamp } }
// Any error          -> ErrorResponse

Structural Templates

Create structural templates for common operation types. When adding a new resource to your API, start from the template rather than inventing new patterns. This ensures new additions are consistent with existing patterns automatically.

Behavioral Consistency

Behavioral consistency means equivalent operations behave equivalently. When developers learn how getUser behaves, they should correctly predict how getOrder behaves.

Error Handling Consistency:

Error handling is where behavioral inconsistency is most common and most damaging:

ErrorHandlingConsistency.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
// ❌ Inconsistent error handling - every method surprises you
interface InconsistentService {
    // Returns null when not found
    getUser(id: string): User | null;
    
    // Throws when not found
    getOrder(id: string): Order; // throws NotFoundException
    
    // Returns undefined when not found
    getProduct(id: string): Product | undefined;
    
    // Returns a result object with error flag
    getPayment(id: string): { success: boolean; data?: Payment; error?: string };
}
 
// Developers must remember 4 different error handling patterns!
 
// ✅ Consistent error handling - one pattern to learn
interface ConsistentService {
    // All "get" operations follow the same pattern:
    // - Return entity if found
    // - Throw NotFoundException if not found
    // - Throw specific typed errors for other failures
    
    getUser(id: string): User;       // throws NotFoundException
    getOrder(id: string): Order;     // throws NotFoundException
    getProduct(id: string): Product; // throws NotFoundException
    getPayment(id: string): Payment; // throws NotFoundException
    
    // For methods where "not found" is expected, use different naming:
    findUserByEmail(email: string): User | null;  // null is valid result
    findOrderByReference(ref: string): Order | null;
}
 
// Exception hierarchy is also consistent:
class ServiceError extends Error { /* base for all errors */ }
 
class NotFoundError extends ServiceError { 
    constructor(public readonly resource: string, public readonly id: string) {
        super(`${resource} with id '${id}' not found`);
    }
}
 
class ValidationError extends ServiceError { /* ... */ }
class AuthorizationError extends ServiceError { /* ... */ }
class ConflictError extends ServiceError { /* ... */ }

Null Handling Consistency:

Decide on a null-handling strategy and apply it universally:

Null Handling Strategy Options
Strategy	When Not Found	When Empty Collection	Pro/Con
Throw exceptions	Throw NotFoundException	Return empty array []	Clear intent, but try/catch overhead
Return null/undefined	Return null	Return empty array []	No exceptions, but null checks everywhere
Optional type	Return Optional.empty()	Return empty List	Type-safe, but API overhead
Result type	Return Result.failure()	Return Result.success([])	Explicit handling, but verbose

Idempotency Consistency:

Establish consistent idempotency rules:

Idempotency Patterns

•GET/HEAD operations: Always idempotent (no side effects)
•DELETE operations: Idempotent (deleting non-existent returns success, not error)
•PUT operations: Idempotent (same request produces same result)
•POST operations: Not inherently idempotent, but support idempotency keys for critical operations
•PATCH operations: Decide and document—idempotent if replacing values, not if incrementing

IdempotentDelete.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
// Idempotent delete: succeeds whether resource exists or not
async function deleteUser(userId: string): Promise<void> {
    const exists = await this.repository.exists(userId);
    
    if (exists) {
        await this.repository.delete(userId);
    }
    
    // No error if already deleted - operation is idempotent
    // Client can safely retry without checking if deletion succeeded
}
 
// POST with idempotency key for safe retries
async function createOrder(
    data: OrderData,
    options?: { idempotencyKey?: string }
): Promise<Order> {
    if (options?.idempotencyKey) {
        const existing = await this.findByIdempotencyKey(options.idempotencyKey);
        if (existing) {
            return existing; // Return previously created order
        }
    }
    
    const order = await this.repository.create({
        ...data,
        idempotencyKey: options?.idempotencyKey
    });
    
    return order;
}

Behavioral Inconsistency is the Hardest to Fix

Once developers depend on specific behaviors, changing them breaks their code. Structural and naming inconsistencies can sometimes be papered over with aliases, but behavioral inconsistencies create deep problems. Get behavior right from the start.

Consistency Anti-Patterns

Recognizing consistency anti-patterns helps you avoid common pitfalls. Here are the most damaging patterns to watch for:

Anti-Pattern 1: The Historical Accident

Different developers at different times invented different conventions, and nobody unified them:

HistoricalAccident.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// 2019: First developer
getUser(id: string): User | null
 
// 2020: Second developer (didn't look at existing code)
fetchOrder(orderId: number): Promise<Order>
 
// 2021: Third developer (copied a different codebase)
async loadProduct(productId: string): Promise<ProductDTO>
 
// 2022: Fourth developer (following a new framework)
retrievePayment(paymentRef: string): Observable<PaymentResult>
 
// Result: Four different patterns for the same concept
// - get vs fetch vs load vs retrieve
// - id types: string vs number vs "Ref"
// - sync vs Promise vs Observable
// - return types: entity vs DTO vs Result vs null

Anti-Pattern 2: The Special Snowflake

One resource that's treated differently from all others for historical or "good" reasons:

SpecialSnowflake.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
// Normal resources follow the pattern
interface UserApi {
    list(options?: ListOptions): Promise<User[]>
    get(id: string): Promise<User>
    create(data: UserData): Promise<User>
    update(id: string, data: Partial<User>): Promise<User>
    delete(id: string): Promise<void>
}
 
// But the "special" resource is different because... reasons
interface ConfigurationApi {
    // Different naming
    fetchAll(): Promise<Configuration[]>  // Why not list()?
    
    // Different parameter style  
    getConfiguration(key: string, namespace: string): Promise<Configuration>  // Why two params?
    
    // Different return type
    setConfiguration(config: Configuration): Promise<{ success: boolean }>  // Why not return entity?
    
    // Different error handling
    deleteConfiguration(key: string): Promise<number>  // Returns count? Why?
}

Anti-Pattern 3: The Copy-Paste Mutation

Code copied from external sources without adapting to local conventions:

CopyPasteMutation.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Your API style (camelCase, Promise-based, TypeScript)
interface OrderService {
    getOrder(orderId: string): Promise<Order>
}
 
// Copied from a Java tutorial (different naming style)
interface PaymentService {
    get_payment_by_id(payment_id: String): Promise<Payment>  // snake_case?!
}
 
// Copied from a Python library (different null handling)
interface ShippingService {
    get_shipment(id: string): Promise<Shipment | None | undefined>  // None?!
}

Anti-Pattern 4: The Premature Generalization

One area uses an "advanced" pattern that doesn't match the rest of the API:

PrematureGeneralization.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Most of the API: simple, direct methods
getUser(id: string): User
createUser(data: UserData): User
updateUser(id: string, data: Partial<User>): User
 
// But one resource uses "Command pattern" because someone read about CQRS:
interface OrderApi {
    execute(command: Command): CommandResult
}
 
// Now consumers need to:
const order = await orderApi.execute({
    type: 'CreateOrder',
    payload: { items: [...] },
    metadata: { correlationId: '...' }
}) as CreateOrderResult;
 
// Instead of:
const order = await orderApi.createOrder({ items: [...] });
 
// The "advanced" pattern doesn't serve users—it just creates inconsistency

Code Review for Consistency

Make consistency a first-class code review criterion. Before any API addition, ask: 'Does this follow our established patterns?' If it doesn't, either align it with existing patterns or make a deliberate decision to change the patterns everywhere.

Maintaining Consistency at Scale

As APIs grow and teams expand, maintaining consistency becomes challenging. Here are strategies that work at scale:

1. Style Guides and Standards Documents:

Create comprehensive documentation of your conventions:

API Style Guide Contents

•Naming conventions: Vocabulary, grammar, casing, abbreviation rules
•Structural patterns: Parameter ordering, options objects, response envelopes
•Behavioral patterns: Error handling, null handling, async patterns, idempotency
•Examples: Concrete examples for each pattern, both positive and negative
•Rationale: Why these patterns were chosen (helps future maintainers)
•Change process: How to propose and adopt new patterns

2. Automated Enforcement:

Human review alone can't catch everything. Automate what you can:

AutomatedEnforcement.ts
TypeScript (ESLint)
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
// Custom ESLint rules for API consistency
module.exports = {
    rules: {
        // Enforce method naming patterns
        'api/method-naming': {
            create(context) {
                return {
                    MethodDefinition(node) {
                        const name = node.key.name;
                        
                        // CRUD methods must start with standard verbs
                        const crudPattern = /^(get|create|update|delete|list)([A-Z][a-z]+)+$/;
                        const boolPattern = /^(is|has|can)[A-Z]/;
                        
                        if (isApiMethod(node) && !crudPattern.test(name) && !boolPattern.test(name)) {
                            context.report({
                                node,
                                message: `API method "${name}" doesn't follow naming convention`
                            });
                        }
                    }
                };
            }
        },
        
        // Enforce consistent error handling
        'api/consistent-errors': { /* ... */ },
        
        // Enforce parameter ordering
        'api/parameter-order': { /* ... */ }
    }
};

3. Templates and Generators:

Make the right thing easy by providing templates:

ApiGenerator.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
// Code generator that creates consistent API scaffolding
// Input: resource name
// Output: fully consistent interface and implementation
 
function generateResourceApi(resourceName: string) {
    const singular = resourceName;
    const plural = pluralize(resourceName);
    const pascalSingular = toPascalCase(singular);
    
    return `
interface ${pascalSingular}Api {
    list(options?: ListOptions): Promise<${pascalSingular}[]>;
    get(id: string): Promise<${pascalSingular}>;
    create(data: ${pascalSingular}Data): Promise<${pascalSingular}>;
    update(id: string, data: Partial<${pascalSingular}Data>): Promise<${pascalSingular}>;
    delete(id: string): Promise<void>;
}
 
// Generated implementation follows all patterns automatically
class ${pascalSingular}Service implements ${pascalSingular}Api {
    async get(id: string): Promise<${pascalSingular}> {
        const entity = await this.repository.findById(id);
        if (!entity) {
            throw new NotFoundError('${singular}', id);
        }
        return entity;
    }
    // ... all other methods follow the same patterns
}
`;
}
 
// Now "plop generate resource product" creates 100% consistent code

4. Design Reviews:

For significant API changes, conduct design reviews focused on consistency:

API Design Review Checklist

•Does this follow our established naming conventions?
•Are parameter types and ordering consistent with similar operations?
•Does error handling match our patterns?
•Is the response structure consistent with our envelopes?
•If this introduces a new pattern, should that pattern be applied elsewhere?
•Have we updated our style guide to reflect any new decisions?

Consistency Debt

Inconsistency is technical debt. Like other debt, it compounds over time. Addressing it early is cheaper than addressing it later. Allocate time to fix inconsistencies before they become entrenched across too many consumers.

When to Break Consistency

Consistency is a means to an end—usability—not an end in itself. There are cases where violating internal consistency is the right choice:

1. External Standard Alignment:

When interacting with external standards, their conventions may take precedence:

ExternalStandards.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Your internal convention: camelCase
interface UserApi {
    getUser(userId: string): User
}
 
// OAuth2 standard uses snake_case - match the standard, not internal convention
interface OAuth2Token {
    access_token: string;  // Standard OAuth2 field names
    token_type: string;
    expires_in: number;
    refresh_token: string;
}
 
// HTTP headers use Title-Case - match HTTP conventions
interface RequestHeaders {
    'Content-Type': string;
    'Authorization': string;
    'X-Request-Id': string;
}

2. Avoiding Worse Inconsistencies:

Sometimes breaking one convention maintains a more important consistency:

AvoidingWorseInconsistency.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Convention: All methods return Promise<Entity>
getUser(id: string): Promise<User>
getOrder(id: string): Promise<Order>
 
// But for performance-critical data, you need sync access
// Breaking the async convention is better than:
// 1. Making developers await unnecessarily 
// 2. Creating fake async wrappers
 
// Better: Clear naming indicates the difference
getUserAsync(id: string): Promise<User>  // Network call, async
getUserFromCache(id: string): User | null  // Local cache, sync
 
// The naming makes the consistency break explicit and justified

3. Safety Over Consistency:

Security or correctness concerns can override consistency:

SafetyOverConsistency.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// Convention: delete is idempotent, returns void
deleteUser(id: string): Promise<void>
deleteOrder(id: string): Promise<void>
 
// But for financial records, deletion should be explicit
// Breaking idempotency convention for audit safety
deletePaymentRecord(id: string): Promise<DeleteConfirmation>  
 
interface DeleteConfirmation {
    deleted: boolean;       // Was something actually deleted?
    recordId: string;       // What was deleted?
    deletedAt: Date;        // When was it deleted?
    previousBalance: Money; // What was the balance (for audit)?
}
 
// This inconsistency is documented and justified by compliance requirements

4. When Consistency Conflicts with Usability:

If following a pattern would make the API less usable for a specific case, usability wins:

Justified Inconsistency Guidelines

•Document the exception: Explain why this case is different in the API documentation
•Make it obvious: Use naming or structure that signals the difference
•Isolate the exception: Don't let the exception infect neighboring patterns
•Evaluate alternatives: Are there ways to achieve the goal without breaking consistency?
•Consider the precedent: Will this encourage other unjustified exceptions?

The Slippery Slope

Every exception creates precedent. 'We made an exception for X, why not Y?' If you make exceptions too freely, you lose consistency entirely. Reserve exceptions for genuinely exceptional cases, document them thoroughly, and resist the temptation to normalize them.

Summary: Consistency in API Design

Consistency transforms an API from a collection of features into a coherent system. When patterns transfer across the API, developers learn once and apply everywhere, making the entire surface area feel smaller and more approachable.

Let's consolidate the key insights:

Key Takeaways

•Consistency spans multiple dimensions: Naming, structural, behavioral, and semantic consistency all contribute to a unified experience.
•Build systematic naming conventions: Establish vocabulary, patterns, grammatical rules, and casing conventions—then apply them universally.
•Create structural templates: Consistent parameter ordering, options objects, and response envelopes make the API predictable.
•Behavioral consistency is critical: Error handling, null handling, and idempotency patterns must be uniform across operations.
•Watch for anti-patterns: Historical accidents, special snowflakes, copy-paste mutations, and premature generalizations erode consistency.
•Enforce consistency at scale: Style guides, automated linting, code generators, and design reviews maintain consistency as teams grow.
•Break consistency deliberately: When external standards, safety, or usability require exceptions, document and isolate them.

What's Next:

We've established the principles—contract thinking, usability, and consistency. The next page brings these together into a systematic API design process: how to apply these principles step-by-step when designing new APIs or evaluating existing ones.

Page Complete

You now understand consistency as a multi-dimensional design property that makes APIs learnable and predictable. Consistency isn't automatic—it requires deliberate effort, systematic conventions, and ongoing enforcement. The investment pays off in developer productivity and satisfaction.

3 / 4

Loading learning content...

System Design (LLD)API & Interface Design

What Is a Good API?

LevelIntermediate

Duration60 mins

TopicAPI & Interface Design

3 / 4

Consistency in API Design

The Multiplier Effect of Consistency

What You Will Learn

Dimensions of Consistency

Consistency isn't a single property—it spans multiple dimensions that together create a unified developer experience.

1. Naming Consistency:

Names are the first thing developers encounter. Consistent naming means:

Naming Consistency Elements

•Vocabulary consistency: The same word means the same thing everywhere (user, never account/member/profile interchangeably)
•Grammatical consistency: Same parts of speech for same concepts (verbs for actions: get, create, delete)
•Casing consistency: Uniform casing convention (camelCase, snake_case, PascalCase) throughout
•Abbreviation consistency: Either always abbreviate or never (not getUserId + getUsrEmail)
•Pluralization consistency: Consistent handling of collections (users vs user_list vs userArray)

2. Structural Consistency:

The shape and organization of API elements should follow predictable patterns:

Structural Consistency Elements

•Parameter order: Consistent ordering (e.g., required before optional, resource ID before data)
•Return type patterns: Similar operations return similar structures
•Request/response shapes: Consistent envelope structure, pagination patterns, metadata placement
•Hierarchy organization: Predictable nesting and grouping of related operations
•Configuration patterns: Same approach to options objects, defaults, and overrides

3. Behavioral Consistency:

How operations behave should be predictable:

Behavioral Consistency Elements

•Error handling patterns: Same error types, codes, and messages for equivalent situations
•Null handling: Consistent treatment (return null, throw, return empty collection)
•Side effect patterns: Equivalent operations have equivalent side effects
•Async patterns: Consistent use of callbacks, promises, or async/await
•Idempotency: Consistent retry-safety behavior for similar operations

4. Semantic Consistency:

The meaning of operations and concepts should be stable:

Semantic Consistency Elements

•Operation semantics: delete always means the same thing (soft delete? hard delete? archival?)
•Field semantics: createdAt always means the same thing with the same format
•Status semantics: active means the same thing for users, orders, subscriptions
•Relationship semantics: Parent-child, ownership, and reference relationships work the same way

Consistency Establishes Expectations

Naming Convention Systems

Establishing a systematic naming convention is the foundation of API consistency. A well-designed naming system makes the right name obvious and wrong names stand out.

Building a Naming Convention:

1. Choose a Vocabulary:

Decide on standard terms for common concepts:

Example Vocabulary Standardization
Concept	Standard Term	Rejected Alternatives
Fetch a resource	get	fetch, retrieve, find, load, read
Create a resource	create	add, new, make, insert, post
Update a resource	update	modify, change, edit, patch, set
Remove a resource	delete	remove, destroy, drop, erase
Collection of items	list	getAll, findAll, query, fetch, index
Entity identifier	id	identifier, key, uid, guid

2. Define Naming Patterns:

Create templates for common operations:

NamingPatterns.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
// Naming pattern templates
// For service methods:
 
// CRUD operations: {verb}{Resource}
getUser(id: string): User
createUser(data: UserData): User
updateUser(id: string, data: Partial<UserData>): User
deleteUser(id: string): void
 
// Collection operations: list{Resources}
listUsers(query?: QueryOptions): User[]
listOrders(query?: QueryOptions): Order[]
 
// Relationship operations: {verb}{Resource}{Relationship}
getUserOrders(userId: string): Order[]
getOrderItems(orderId: string): Item[]
 
// Status changes: {verb}{Resource} where verb indicates target state
activateUser(id: string): User
deactivateUser(id: string): User
publishPost(id: string): Post
archivePost(id: string): Post
 
// Check operations: is{Condition} or has{Property} or can{Action}
isUserActive(id: string): boolean
hasUserPermission(userId: string, permission: string): boolean
canUserPerformAction(userId: string, action: string): boolean
 
// Batch operations: {verb}{Resources} (plural)
createUsers(data: UserData[]): User[]
deleteUsers(ids: string[]): void
 
// Search operations: search{Resources} or find{Resources}By{Criteria}
searchUsers(query: string): User[]
findUsersByRole(role: string): User[]

3. Establish Grammatical Rules:

Grammatical Consistency Rules

•Methods are verbs or verb phrases: getUser, validatePayment, processOrder
•Types and classes are nouns: User, PaymentProcessor, OrderService
•Boolean methods/properties start with is/has/can: isValid, hasPermission, canDelete
•Factory methods use create or build: createOrder, buildRequest
•Conversion methods use to or as: toJSON, asString, toDTO
•Event handlers use on or handle: onUserCreated, handleOrderPlaced

4. Casing Conventions:

Casing by Element Type
Element	Convention	Example
Variables and parameters	camelCase	userId, orderTotal
Methods and functions	camelCase	getUser, calculateTotal
Classes and types	PascalCase	UserService, OrderItem
Constants	SCREAMING_SNAKE_CASE	MAX_RETRY_COUNT
Enum values	SCREAMING_SNAKE_CASE or PascalCase	ORDER_STATUS.PENDING
JSON keys (REST)	camelCase or snake_case (pick one)	{ userId: 123 }

Document Your Conventions

Structural Patterns

Beyond naming, the structural organization of your API must follow consistent patterns. Developers should be able to predict structure before they see documentation.

Parameter Ordering:

Establish a standard parameter order and apply it everywhere:

ParameterOrdering.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// Standard parameter ordering convention:
// 1. Target/Subject identifier (what we're operating on)
// 2. Data/Payload (what we're providing)
// 3. Options (how to perform the operation)
 
// ✅ Consistent ordering across all methods
updateUser(userId: string, data: Partial<User>, options?: UpdateOptions): User
updateOrder(orderId: string, data: Partial<Order>, options?: UpdateOptions): Order
updateProduct(productId: string, data: Partial<Product>, options?: UpdateOptions): Product
 
// ❌ Inconsistent ordering - breaks expectations
updateUser(userId: string, data: Partial<User>): User
updateOrder(data: Partial<Order>, orderId: string): Order  // Why is order different?
updateProduct(options: UpdateOptions, productId: string, data: Partial<Product>): Product  // ?!
 
// Callback positioning: always last (convention in most languages)
fetchData(url: string, options: FetchOptions, callback: Callback): void
 
// Promise-based methods: no callback parameter
fetchData(url: string, options?: FetchOptions): Promise<Response>

Options Object Patterns:

When methods need many optional parameters, use options objects with consistent structure:

OptionsPatterns.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
// Common options structure across all list operations
interface ListOptions {
    // Pagination (same shape everywhere)
    limit?: number;
    offset?: number;
    cursor?: string;
    
    // Filtering (consistent pattern)
    filter?: Record<string, unknown>;
    
    // Sorting (consistent pattern)
    orderBy?: string | { field: string; direction: 'asc' | 'desc' }[];
    
    // Field selection (consistent pattern)
    fields?: string[];
    
    // Expansion (consistent pattern)
    expand?: string[];
}
 
// All list methods accept the same options shape
listUsers(options?: ListOptions): Promise<PaginatedResult<User>>
listOrders(options?: ListOptions): Promise<PaginatedResult<Order>>
listProducts(options?: ListOptions): Promise<PaginatedResult<Product>>
 
// Response structure is also consistent
interface PaginatedResult<T> {
    data: T[];
    pagination: {
        total: number;
        limit: number;
        offset: number;
        hasMore: boolean;
        nextCursor?: string;
    };
    metadata?: {
        executionTimeMs: number;
    };
}

Response Envelope Patterns:

For REST APIs and similar interfaces, consistent response envelopes eliminate guesswork:

ResponseEnvelopes.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
// Consistent response envelopes
 
// Single resource response
interface SingleResponse<T> {
    data: T;
    meta?: {
        requestId: string;
        timestamp: string;
    };
}
 
// Collection response
interface CollectionResponse<T> {
    data: T[];
    pagination: PaginationInfo;
    meta?: {
        requestId: string;
        timestamp: string;
        totalCount: number;
    };
}
 
// Error response
interface ErrorResponse {
    error: {
        code: string;
        message: string;
        details?: ValidationError[] | Record<string, unknown>;
        requestId: string;
        timestamp: string;
    };
}
 
// All endpoints follow the same pattern:
// GET /users/:id     -> SingleResponse<User>
// GET /users         -> CollectionResponse<User>
// POST /users        -> SingleResponse<User>
// PATCH /users/:id   -> SingleResponse<User>
// DELETE /users/:id  -> { meta: { requestId, timestamp } }
// Any error          -> ErrorResponse

Structural Templates

Behavioral Consistency

Behavioral consistency means equivalent operations behave equivalently. When developers learn how getUser behaves, they should correctly predict how getOrder behaves.

Error Handling Consistency:

Error handling is where behavioral inconsistency is most common and most damaging:

ErrorHandlingConsistency.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
// ❌ Inconsistent error handling - every method surprises you
interface InconsistentService {
    // Returns null when not found
    getUser(id: string): User | null;
    
    // Throws when not found
    getOrder(id: string): Order; // throws NotFoundException
    
    // Returns undefined when not found
    getProduct(id: string): Product | undefined;
    
    // Returns a result object with error flag
    getPayment(id: string): { success: boolean; data?: Payment; error?: string };
}
 
// Developers must remember 4 different error handling patterns!
 
// ✅ Consistent error handling - one pattern to learn
interface ConsistentService {
    // All "get" operations follow the same pattern:
    // - Return entity if found
    // - Throw NotFoundException if not found
    // - Throw specific typed errors for other failures
    
    getUser(id: string): User;       // throws NotFoundException
    getOrder(id: string): Order;     // throws NotFoundException
    getProduct(id: string): Product; // throws NotFoundException
    getPayment(id: string): Payment; // throws NotFoundException
    
    // For methods where "not found" is expected, use different naming:
    findUserByEmail(email: string): User | null;  // null is valid result
    findOrderByReference(ref: string): Order | null;
}
 
// Exception hierarchy is also consistent:
class ServiceError extends Error { /* base for all errors */ }
 
class NotFoundError extends ServiceError { 
    constructor(public readonly resource: string, public readonly id: string) {
        super(`${resource} with id '${id}' not found`);
    }
}
 
class ValidationError extends ServiceError { /* ... */ }
class AuthorizationError extends ServiceError { /* ... */ }
class ConflictError extends ServiceError { /* ... */ }

Null Handling Consistency:

Decide on a null-handling strategy and apply it universally:

Null Handling Strategy Options
Strategy	When Not Found	When Empty Collection	Pro/Con
Throw exceptions	Throw NotFoundException	Return empty array []	Clear intent, but try/catch overhead
Return null/undefined	Return null	Return empty array []	No exceptions, but null checks everywhere
Optional type	Return Optional.empty()	Return empty List	Type-safe, but API overhead
Result type	Return Result.failure()	Return Result.success([])	Explicit handling, but verbose

Idempotency Consistency:

Establish consistent idempotency rules:

Idempotency Patterns

•GET/HEAD operations: Always idempotent (no side effects)
•DELETE operations: Idempotent (deleting non-existent returns success, not error)
•PUT operations: Idempotent (same request produces same result)
•POST operations: Not inherently idempotent, but support idempotency keys for critical operations
•PATCH operations: Decide and document—idempotent if replacing values, not if incrementing

IdempotentDelete.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
// Idempotent delete: succeeds whether resource exists or not
async function deleteUser(userId: string): Promise<void> {
    const exists = await this.repository.exists(userId);
    
    if (exists) {
        await this.repository.delete(userId);
    }
    
    // No error if already deleted - operation is idempotent
    // Client can safely retry without checking if deletion succeeded
}
 
// POST with idempotency key for safe retries
async function createOrder(
    data: OrderData,
    options?: { idempotencyKey?: string }
): Promise<Order> {
    if (options?.idempotencyKey) {
        const existing = await this.findByIdempotencyKey(options.idempotencyKey);
        if (existing) {
            return existing; // Return previously created order
        }
    }
    
    const order = await this.repository.create({
        ...data,
        idempotencyKey: options?.idempotencyKey
    });
    
    return order;
}

Behavioral Inconsistency is the Hardest to Fix

Consistency Anti-Patterns

Recognizing consistency anti-patterns helps you avoid common pitfalls. Here are the most damaging patterns to watch for:

Anti-Pattern 1: The Historical Accident

Different developers at different times invented different conventions, and nobody unified them:

HistoricalAccident.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// 2019: First developer
getUser(id: string): User | null
 
// 2020: Second developer (didn't look at existing code)
fetchOrder(orderId: number): Promise<Order>
 
// 2021: Third developer (copied a different codebase)
async loadProduct(productId: string): Promise<ProductDTO>
 
// 2022: Fourth developer (following a new framework)
retrievePayment(paymentRef: string): Observable<PaymentResult>
 
// Result: Four different patterns for the same concept
// - get vs fetch vs load vs retrieve
// - id types: string vs number vs "Ref"
// - sync vs Promise vs Observable
// - return types: entity vs DTO vs Result vs null

Anti-Pattern 2: The Special Snowflake

One resource that's treated differently from all others for historical or "good" reasons:

SpecialSnowflake.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
// Normal resources follow the pattern
interface UserApi {
    list(options?: ListOptions): Promise<User[]>
    get(id: string): Promise<User>
    create(data: UserData): Promise<User>
    update(id: string, data: Partial<User>): Promise<User>
    delete(id: string): Promise<void>
}
 
// But the "special" resource is different because... reasons
interface ConfigurationApi {
    // Different naming
    fetchAll(): Promise<Configuration[]>  // Why not list()?
    
    // Different parameter style  
    getConfiguration(key: string, namespace: string): Promise<Configuration>  // Why two params?
    
    // Different return type
    setConfiguration(config: Configuration): Promise<{ success: boolean }>  // Why not return entity?
    
    // Different error handling
    deleteConfiguration(key: string): Promise<number>  // Returns count? Why?
}

Anti-Pattern 3: The Copy-Paste Mutation

Code copied from external sources without adapting to local conventions:

CopyPasteMutation.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Your API style (camelCase, Promise-based, TypeScript)
interface OrderService {
    getOrder(orderId: string): Promise<Order>
}
 
// Copied from a Java tutorial (different naming style)
interface PaymentService {
    get_payment_by_id(payment_id: String): Promise<Payment>  // snake_case?!
}
 
// Copied from a Python library (different null handling)
interface ShippingService {
    get_shipment(id: string): Promise<Shipment | None | undefined>  // None?!
}

Anti-Pattern 4: The Premature Generalization

One area uses an "advanced" pattern that doesn't match the rest of the API:

PrematureGeneralization.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Most of the API: simple, direct methods
getUser(id: string): User
createUser(data: UserData): User
updateUser(id: string, data: Partial<User>): User
 
// But one resource uses "Command pattern" because someone read about CQRS:
interface OrderApi {
    execute(command: Command): CommandResult
}
 
// Now consumers need to:
const order = await orderApi.execute({
    type: 'CreateOrder',
    payload: { items: [...] },
    metadata: { correlationId: '...' }
}) as CreateOrderResult;
 
// Instead of:
const order = await orderApi.createOrder({ items: [...] });
 
// The "advanced" pattern doesn't serve users—it just creates inconsistency

Code Review for Consistency

Maintaining Consistency at Scale

As APIs grow and teams expand, maintaining consistency becomes challenging. Here are strategies that work at scale:

1. Style Guides and Standards Documents:

Create comprehensive documentation of your conventions:

API Style Guide Contents

•Naming conventions: Vocabulary, grammar, casing, abbreviation rules
•Structural patterns: Parameter ordering, options objects, response envelopes
•Behavioral patterns: Error handling, null handling, async patterns, idempotency
•Examples: Concrete examples for each pattern, both positive and negative
•Rationale: Why these patterns were chosen (helps future maintainers)
•Change process: How to propose and adopt new patterns

2. Automated Enforcement:

Human review alone can't catch everything. Automate what you can:

AutomatedEnforcement.ts
TypeScript (ESLint)
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
// Custom ESLint rules for API consistency
module.exports = {
    rules: {
        // Enforce method naming patterns
        'api/method-naming': {
            create(context) {
                return {
                    MethodDefinition(node) {
                        const name = node.key.name;
                        
                        // CRUD methods must start with standard verbs
                        const crudPattern = /^(get|create|update|delete|list)([A-Z][a-z]+)+$/;
                        const boolPattern = /^(is|has|can)[A-Z]/;
                        
                        if (isApiMethod(node) && !crudPattern.test(name) && !boolPattern.test(name)) {
                            context.report({
                                node,
                                message: `API method "${name}" doesn't follow naming convention`
                            });
                        }
                    }
                };
            }
        },
        
        // Enforce consistent error handling
        'api/consistent-errors': { /* ... */ },
        
        // Enforce parameter ordering
        'api/parameter-order': { /* ... */ }
    }
};

3. Templates and Generators:

Make the right thing easy by providing templates:

ApiGenerator.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
// Code generator that creates consistent API scaffolding
// Input: resource name
// Output: fully consistent interface and implementation
 
function generateResourceApi(resourceName: string) {
    const singular = resourceName;
    const plural = pluralize(resourceName);
    const pascalSingular = toPascalCase(singular);
    
    return `
interface ${pascalSingular}Api {
    list(options?: ListOptions): Promise<${pascalSingular}[]>;
    get(id: string): Promise<${pascalSingular}>;
    create(data: ${pascalSingular}Data): Promise<${pascalSingular}>;
    update(id: string, data: Partial<${pascalSingular}Data>): Promise<${pascalSingular}>;
    delete(id: string): Promise<void>;
}
 
// Generated implementation follows all patterns automatically
class ${pascalSingular}Service implements ${pascalSingular}Api {
    async get(id: string): Promise<${pascalSingular}> {
        const entity = await this.repository.findById(id);
        if (!entity) {
            throw new NotFoundError('${singular}', id);
        }
        return entity;
    }
    // ... all other methods follow the same patterns
}
`;
}
 
// Now "plop generate resource product" creates 100% consistent code

4. Design Reviews:

For significant API changes, conduct design reviews focused on consistency:

API Design Review Checklist

•Does this follow our established naming conventions?
•Are parameter types and ordering consistent with similar operations?
•Does error handling match our patterns?
•Is the response structure consistent with our envelopes?
•If this introduces a new pattern, should that pattern be applied elsewhere?
•Have we updated our style guide to reflect any new decisions?

Consistency Debt

When to Break Consistency

Consistency is a means to an end—usability—not an end in itself. There are cases where violating internal consistency is the right choice:

1. External Standard Alignment:

When interacting with external standards, their conventions may take precedence:

ExternalStandards.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Your internal convention: camelCase
interface UserApi {
    getUser(userId: string): User
}
 
// OAuth2 standard uses snake_case - match the standard, not internal convention
interface OAuth2Token {
    access_token: string;  // Standard OAuth2 field names
    token_type: string;
    expires_in: number;
    refresh_token: string;
}
 
// HTTP headers use Title-Case - match HTTP conventions
interface RequestHeaders {
    'Content-Type': string;
    'Authorization': string;
    'X-Request-Id': string;
}

2. Avoiding Worse Inconsistencies:

Sometimes breaking one convention maintains a more important consistency:

AvoidingWorseInconsistency.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Convention: All methods return Promise<Entity>
getUser(id: string): Promise<User>
getOrder(id: string): Promise<Order>
 
// But for performance-critical data, you need sync access
// Breaking the async convention is better than:
// 1. Making developers await unnecessarily 
// 2. Creating fake async wrappers
 
// Better: Clear naming indicates the difference
getUserAsync(id: string): Promise<User>  // Network call, async
getUserFromCache(id: string): User | null  // Local cache, sync
 
// The naming makes the consistency break explicit and justified

3. Safety Over Consistency:

Security or correctness concerns can override consistency:

SafetyOverConsistency.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// Convention: delete is idempotent, returns void
deleteUser(id: string): Promise<void>
deleteOrder(id: string): Promise<void>
 
// But for financial records, deletion should be explicit
// Breaking idempotency convention for audit safety
deletePaymentRecord(id: string): Promise<DeleteConfirmation>  
 
interface DeleteConfirmation {
    deleted: boolean;       // Was something actually deleted?
    recordId: string;       // What was deleted?
    deletedAt: Date;        // When was it deleted?
    previousBalance: Money; // What was the balance (for audit)?
}
 
// This inconsistency is documented and justified by compliance requirements

4. When Consistency Conflicts with Usability:

If following a pattern would make the API less usable for a specific case, usability wins:

Justified Inconsistency Guidelines

•Document the exception: Explain why this case is different in the API documentation
•Make it obvious: Use naming or structure that signals the difference
•Isolate the exception: Don't let the exception infect neighboring patterns
•Evaluate alternatives: Are there ways to achieve the goal without breaking consistency?
•Consider the precedent: Will this encourage other unjustified exceptions?

The Slippery Slope

Summary: Consistency in API Design

Let's consolidate the key insights:

Key Takeaways

•Consistency spans multiple dimensions: Naming, structural, behavioral, and semantic consistency all contribute to a unified experience.
•Build systematic naming conventions: Establish vocabulary, patterns, grammatical rules, and casing conventions—then apply them universally.
•Create structural templates: Consistent parameter ordering, options objects, and response envelopes make the API predictable.
•Behavioral consistency is critical: Error handling, null handling, and idempotency patterns must be uniform across operations.
•Watch for anti-patterns: Historical accidents, special snowflakes, copy-paste mutations, and premature generalizations erode consistency.
•Enforce consistency at scale: Style guides, automated linting, code generators, and design reviews maintain consistency as teams grow.
•Break consistency deliberately: When external standards, safety, or usability require exceptions, document and isolate them.

What's Next:

Page Complete

3 / 4