API Design and Astonishment

An API—whether a library interface, a REST endpoint, a CLI tool, or an SDK—is a contract with users you may never meet. Unlike internal code where you can walk over to a colleague's desk to ask questions, API users are on their own. They will use your API based on their assumptions, and when those assumptions are wrong, they will experience bugs, frustration, and wasted time.

The API amplification effect:

If your internal function confuses one teammate, you've lost an hour. If your public API confuses 10,000 developers, you've lost 10,000 hours—plus the bug reports, the Stack Overflow questions, the angry tweets, and the developers who silently switch to a competitor.

API design is where the Principle of Least Astonishment is most critical because:

• You can't explain ambiguity — Users won't call you to ask what parse() does
• You can't fix mistakes easily — Changing behavior breaks existing users
• Documentation is not read — Most users try the obvious thing first
• Conventions are universal — Your users bring expectations from every other API they've used

Rico Mariani coined the term 'Pit of Success' to describe API design that makes falling into correct usage easier than falling into incorrect usage. The idea is simple but profound:

A well-designed API should make it easy to do the right thing, hard to do the wrong thing, and obvious when something goes wrong.

This is the POLA aspiration for API design: users should guess correctly on their first try.

In API design, consistency is king. A consistent API is predictable because patterns learned on one method transfer to all other methods. An inconsistent API forces users to relearn for each new endpoint.

Dimensions of Consistency:

1. Naming Consistency

Use the same term for the same concept everywhere. If you call it 'user' in one endpoint, don't call it 'account' or 'member' in another. If you use 'create' for one resource, don't use 'add' or 'new' for another.

// ❌ Inconsistent naming
GET  /users/{id}          // 'users' 
POST /accounts            // 'accounts'? Is this different?
PUT  /members/{memberId}  // 'members'? 'memberId' not 'id'?

// ✅ Consistent naming  
GET  /users/{id}
POST /users
PUT  /users/{id}

2. Structural Consistency

All responses should have the same structure. All errors should follow the same format. All pagination should work the same way.

// ❌ Inconsistent structure
// Some responses return raw data:
{ "id": 1, "name": "Alice" }

// Others wrap in 'data':
{ "data": { "id": 2, "name": "Bob" }, "meta": {} }

// Errors sometimes use 'error':
{ "error": "Not found" }

// Other times 'message':
{ "message": "User does not exist", "code": 404 }

// ✅ Consistent structure - always same format
{ 
  "data": { "id": 1, "name": "Alice" },
  "meta": { "requestId": "abc123" }
}

{ 
  "error": {
    "code": "NOT_FOUND",
    "message": "User with id 123 not found",
    "requestId": "abc123"
  }
}

3. Behavioral Consistency

Similar operations should behave similarly. If DELETE /users/{id} returns 204 No Content, then DELETE /orders/{id} should also return 204. If one endpoint supports pagination with ?page=1&limit=20, all endpoints should use those same parameter names.

Sensible defaults reduce the configuration burden for common cases. Progressive disclosure reveals complexity only when needed. Together, they make APIs approachable yet powerful.

The Principle of Sensible Defaults:

Every parameter should have a default that works for the majority of users. Users should be able to get started with minimal configuration:

Progressive Disclosure Pattern:

Expose simple interfaces for simple needs, with clear paths to more power:

Level 1: The One-Liner

const result = await api.get('/users/123');

Level 2: Common Options

const result = await api.get('/users/123', {
  headers: { 'X-Request-Id': 'abc' },
  timeout: 10000,
});

Level 3: Full Control

const result = await api.request({
  method: 'GET',
  url: '/users/123',
  headers: { 'X-Request-Id': 'abc' },
  timeout: 10000,
  retry: { attempts: 3, backoff: 'exponential' },
  transform: customTransformer,
  validateStatus: (s) => s < 500,
});

Errors are where astonishment hurts most. When things go wrong, users are already frustrated. Surprising error behavior compounds that frustration into rage-quitting.

Principles for Predictable API Errors:

HTTP methods carry semantics that users expect your API to respect. Violating these semantics astonishes users and breaks their mental model of how HTTP works.

Common Semantic Violations:

❌ GET /users/123/delete — GET with side effects ❌ POST /users/123 — POST for updates (should be PUT or PATCH) ❌ DELETE /users/123 that fails if already deleted — DELETE should be idempotent ❌ PUT /users that creates if not exists with auto-generated ID — PUT should be to specific URI

Making POST Idempotent:

POST is inherently non-idempotent, but you can make it safe with idempotency keys:

APIs must evolve, but evolution must not surprise existing users. Predictable evolution means users know what to expect when versions change.

Versioning Strategies:

Non-Breaking vs Breaking Changes:

Non-Breaking (Safe to Deploy):

• Adding a new endpoint
• Adding an optional field to requests
• Adding a new field to responses
• Adding a new enum value (if clients handle unknown values)
• Adding a new optional parameter

Breaking (Requires Version Bump):

• Removing an endpoint
• Removing a response field
• Changing a field type (string → number)
• Changing endpoint behavior
• Making an optional field required
• Renaming a field
• Changing error codes

Good documentation doesn't just explain what your API does—it sets correct expectations so users are never surprised. But documentation is a last resort; a well-designed API needs minimal documentation.

Documentation Hierarchy:

1. Self-Documenting Design (Best) — The API is so intuitive that users guess correctly
2. Type Definitions — Types communicate structure and constraints at compile time
3. Error Messages — Errors explain what went wrong and how to fix it
4. Inline Documentation — JSDoc, docstrings, annotations
5. Reference Documentation — Full API reference with all endpoints/methods
6. Guides and Tutorials — Step-by-step instructions for common tasks
7. FAQs and Troubleshooting — Answers to things users got wrong

What to Document for POLA:

Focus documentation on things users might get wrong:

• Non-obvious behavior: 'Note: delete() is asynchronous; the resource may still appear in list() for up to 30 seconds.'
• Gotchas: 'Warning: Dates are returned in UTC. Convert to local time on the client.'
• Defaults: 'If not specified, limit defaults to 20 and offset defaults to 0.'
• Limits and constraints: 'Maximum request body size is 1MB. Requests with larger bodies receive 413.'
• Rate limits: 'This endpoint is rate-limited to 100 requests per minute per API key.'
• Idempotency guarantees: 'PUT is idempotent. Safe to retry on timeout.'