Simplicity is a hallmark of well-designed HTTP APIs, but achieving simplicity requires effort. The likelihood that a partner or third-party developer will abandon an API increases as cognitive load grows—with each additional path, parameter, schema, or property adding complexity. Clear design and development policies, combined with strong governance practices, help prevent unnecessary complexity and ensure that simple HTTP APIs are prioritized over more complicated solutions. As technologists, it’s easy to view complexity as a necessary feature of APIs, but in reality, the opposite is true. Simple, intuitive HTTP APIs enhance usability and improve the experience for both producers and consumers. API producers often overwhelm consumers with too many paths, parameters, and properties, when in many cases, a single, focused API resource or capability would suffice.
Simplicity
Policies
Documentation
Documentation is the human-readable representation of your API's surface area. Paths, methods, descriptions, examples -- this is where consumers go to understand what is possible and how to get sta...
Getting Started
Getting started is the single most important thing you can get right for new API consumers. A simple, plain language walkthrough that covers discovery, onboarding, and first API call makes or break...
Governance
Governance is how you get hundreds of APIs moving in the same direction. It is not about control -- it is about a common platform, lifecycle, policies, and rules that help teams ship consistent API...
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.
Plans
Plans are where the business of APIs becomes explicit. Tiers, rate limits, features, and pricing laid out clearly is how you build a sustainable API program that consumers can understand and trust.
Standards
Standards are the building blocks that save everyone time and money. HTTP, JSON, OpenAPI, JSON Schema -- adopting these keeps APIs consistent and interoperable without reinventing the wheel.
Support
Support is one of those things that separates APIs that get adopted from ones that get abandoned. Making it clear how consumers can get help -- email, tickets, forums -- is essential.
Use Cases
Use cases are the who, what, how, and why of an API. Documenting and maintaining them keeps the API aligned with real business needs rather than drifting into features nobody asked for.
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...
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.
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...
Strategies
API Paths Must Conform to the Organization
Your API paths are the most visible thing you put out there, and when they don't follow any organizational standard, the whole thing feels like a junk drawer. I keep finding APIs where every team i...
API Responses Must Be Meaningful and Consistent
I keep seeing APIs where responses feel like a total afterthought. Inconsistent structures, missing status codes, no examples. The reality is your responses are the conversation you are having with...
APIs Are Aligned with Industry Using Standards
Before you go inventing a new schema or process, look at what already exists. I have watched so many teams reinvent the wheel when perfectly good standards were sitting right there waiting to be us...
APIs Are Always Aligned with the Wider Enterprise
Every API needs a real business use case that ties the technical details back to why the enterprise actually cares. I see too many APIs built because someone thought it would be cool, with zero ali...
APIs Are Always Well Documented
Documentation is the front door to your API, and I am still amazed at how many teams leave that door half open. Or locked. You need human-readable docs that cover methods, operations, requests, res...
APIs Must Be Actively Governed
Governance is what keeps things from turning into chaos, but it only works when it is active and ongoing. Not a document someone wrote two years ago. You need a common lifecycle, policies and rules...
APIs Must Be Supported and Have Feedback Loops
Support and feedback loops are what keep the relationship between producers and consumers healthy. Self-service support channels, direct support options, and regular feedback mechanisms that go bey...
APIs Must Reusable Whenever Possible
Reusability is one of those things that separates mature API operations from everyone else. When you make schema, parameters, examples, and error responses modular and interchangeable--not just wit...
Data Should Be Well-Defined and Validated
The schema behind your APIs is where the rubber meets the road. If your data does not have a well-known shape, if it is not validated on the way in and out, you are setting consumers up for surpris...
Onboarding is Always as Easy as Possible
I have been onboarding with APIs for over fifteen years and the best ones always get you from zero to first call in just a couple of steps. Documentation, authentication, SDKs--these need to be eas...
Operations Must Always Be Secure
Security is not something you tack on at the end. It has to be woven into design, development, and run-time from day one. Data, credentials, logs--everything needs to be locked down and operating a...
Operations Must Be Useful and Consistent
Every API operation should do one thing and do it well. That is the Unix philosophy applied to APIs and it still holds up. When your operations follow common standards with consistent naming, clear...
APIs Follow Consistent Design Patterns
Consistency is one of the most underrated qualities in the API landscape. When consumers learn your patterns for naming, pagination, filtering, and error handling once and can apply them across eve...
APIs Deliver an Exceptional Developer Experience
Developer experience is where the technology, business, and politics of APIs all converge. Interactive docs, sandbox environments, realistic examples, intuitive naming--when developers can quickly ...
