All APIs must follow consistent design patterns for naming conventions, media types, pagination, filtering, sorting, and error handling, ensuring that consumers can learn patterns once and apply them across all APIs within the organization.
APIs Follow Consistent Design Patterns
Policies
Naming Conventions
Naming conventions are one of the highest-impact governance decisions you can make. Casing rules for paths, parameters, schemas, and properties create a uniform surface area that developers can nav...
Media Types
Media types define the content formats your APIs support. JSON is the default I see across the landscape, but having a clear policy for content negotiation prevents confusion when multiple formats ...
Idempotency
Idempotency is one of those design principles that separates reliable APIs from fragile ones. Knowing which operations are safe to retry and how idempotency keys work prevents duplicate processing ...
URL Structure
URL structure is one of the most visible parts of API design. Plural nouns, proper casing, no verbs in paths, and reasonable nesting depth create URLs that are intuitive and consistent across all A...
Data Types and Formats
Consistent data types across APIs prevent integration headaches. ISO 8601 for dates, standard number formats, and proper OpenAPI format specifiers mean data serializes the same way everywhere.
Best Practices
Best practices in API design cover the fundamentals -- proper HTTP semantics, content negotiation, resource design, and REST constraints. This is the baseline for quality that every API should meet.
Data Validation
Data validation at the API boundary catches problems before they propagate. Type checking, format enforcement, required fields, and enum validation are the building blocks of data integrity.
Path Trailing Slashes
Trailing slashes on API paths cause more problems than people realize. Some tools treat /users and /users/ as different resources. Keeping paths clean prevents routing and caching issues.
Operation ID Conventions
Operation IDs need consistent conventions because code generators, SDKs, and docs all use them. Inconsistent casing or characters here breaks downstream tooling in ways that are painful to debug.
Path Names
Path naming is one of those things that reveals how much thought went into an API's design. No version numbers in paths, no trailing slashes, no 'api' prefix -- clean paths show discipline.
HTTP Methods
HTTP methods have specific semantics -- GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes. Using them correctly is fundamental to building APIs that work the way consumers expect.
HTTP Status Codes
Status codes are the language APIs use to communicate outcomes. Using 200, 201, 204, 400, 401, 403, 404, 429, and 500 correctly and consistently across operations is non-negotiable.
Pagination
Pagination determines how consumers retrieve large datasets from your APIs. Whether you use cursor-based or offset-based, having a consistent approach with clear metadata is how you scale data access.
Filtering and Sorting
Filtering and sorting conventions should be learned once and applied everywhere. Consistent query parameter patterns for filter, sort, and search make your APIs predictable across the board.
Error Handling
Standardized error handling using RFC 7807 Problem Details gives consumers a consistent way to handle errors across all your APIs. Consistent error codes, messages, and correlation IDs make debuggi...
Experiences
Consistency
When I look across the API landscape, consistency is one of the biggest challenges I see. Every team does things differently, and the surface area of inconsistency just grows until governance becom...
Quality
I see the quality of APIs eroding across the landscape. Teams ship fast and never look back, but consumers feel every rough edge, every missing example, every inconsistent response. Quality is what...
Onboarding
I see teams dealing with massive friction during onboarding. If a consumer can't get from zero to their first successful API call in minutes, you've already lost them. Getting started guides, sandb...
Developer Experience
Developer experience is the thing I'm most passionate about across the API landscape. Poor docs, missing examples, inconsistent patterns, and no tooling -- these are the things that make developers...
Simplicity
I am a big believer that the best APIs are the simple ones. When I see overly complex API designs, I know someone was thinking about their internal architecture instead of the consumer. Keep the su...
Interoperability
Interoperability is where standards really earn their keep in the API landscape. When every API uses different formats, patterns, and conventions, consumers pay the tax every time they try to integ...