Principle: Design APIs from the consumer's perspective

APIs designed from the implementation perspective are hard to use. Internal data models leak into the public interface.

Start with how the API will be USED, not how it's BUILT:

1. Write the client code first:

// Start here - what would the ideal usage look like?
const user = await api.users.get('user-123');
const orders = await api.orders.list({ userId: 'user-123', status: 'active' });
const result = await api.orders.create({ userId: 'user-123', items: [...] });
// THEN implement the server to match

1. Use consistent naming:

- Nouns for resources: /users, /orders (not /getUsers)
- Standard HTTP methods: GET, POST, PUT, DELETE
- Consistent pluralization: /users/123 (not /user/123)
- Consistent casing: camelCase or snake_case (pick one)

1. Don't expose implementation details:

Bad: { "user_row_id": 42, "order_tbl_status_cd": "A" }
Good: { "id": "user-123", "status": "active" }

1. Provide good error responses:

{
"error": { "code": "INVALID_EMAIL", "message": "Email must contain @", "field": "email" }
}

1. Make common things easy, rare things possible:

GET /users # Simple list
GET /users?role=admin&sort=-created # Filtered, sorted
GET /users?fields=id,name # Sparse fieldsets

1. Version from day one (even if v1 for years)

A well-designed API reduces integration time from days to hours. The best APIs feel obvious — you can guess the endpoint without reading docs.