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
The human-readable HTML, Markdown, or PDF representation of the technical surface area of each API, providing path, methods, summaries, description, examples, and the other resources consumers will...
Getting Started
The step by step walk-through for new API consumers, ensuring they have exactly what is needed to discover and onboard, but also help make sure the getting started steps are as simple, plain langua...
Governance
Governance standardizes APIs across teams using a common platform and lifecycle, applying governance policies and rules, and keeping everyone moving in the same direction using common guidance.
Plans
Plans are all about being explicit and transparent with all of the access for an API, breaking down the tiers, rate limits, features, and pricing that is available for API consumers, standardizing ...
Standards
Internet, industry, market, and government standards help make APIs more consistent, but also save time and money for both producer and consumer, while keeping APIs better aligned with existing ind...
Support
Outline what support is available for API consumers, including email, tickets, forums, and paid support services, making it easy for API consumers to understand how they can get the help they need ...
Use Cases
The who, what, how, and why of producing an API, making sure all of the known use cases are accurately described and kept up to date, then used to ensure each API is delivering what is expected wit...
Strategies
API Paths Must Conform to the Organization
All API paths must conform to the overall organizational domain standards, utilizing plain language and a resourceful approach to delivering digital resources and capabilities via HTTP APIs, provid...
API Responses Must Be Meaningful and Consistent
All API responses should follow Internet, industry, and enterprise standards, providing a meaningful and consistent communication and structure, always providing what was intended for API consumers...
APIs Are Aligned with Industry Using Standards
All APIs must be using relevant Internet, industry, and government standards available, ensuring to properly research areas of operations to see what existing standards may exist before the creatio...
APIs Are Always Aligned with the Wider Enterprise
All API contracts must have use cases that align the business reasons why an API is being delivered to consumers with the actual technical details of each API contract, ensuring that operations all...
APIs Are Always Well Documented
All APIs must have human-readable documentation that defines the technical surface area of each API being made available to API consumers, providing a simple, intuitive, and ideally interactive HTM...
APIs Deliver an Exceptional Developer Experience
All APIs must prioritize the developer experience by providing interactive documentation, sandbox environments, realistic examples, and intuitive naming, ensuring that developers can quickly unders...
APIs Follow Consistent Design Patterns
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 th...
APIs Must Be Actively Governed
All APIs being produced must be governed as part of the overall strategy, using the platform, as well as a common API lifecycle, applying policies and rules, and keeping teams moving in the same di...
APIs Must Be Supported and Have Feedback Loops
All APIs must have support mechanisms to ensure API consumers have self-service or direct support channels, as well as regular feedback loops for soliciting feedback or answering specific API quest...
APIs Must Reusable Whenever Possible
The components of any API should be made modular and reusable whenever it makes sense to the business use case, keeping schema, parameters, examples, error responses, and other common parts of an A...
APIs Use the Right Protocol for the Job
I want us to stop treating REST as the answer to every problem and instead pick the protocol that actually fits the job in front of us. When the interaction is event-driven we describe it with Asyn...
Data Should Be Well-Defined and Validated
The schema for data that is sent and received via API should always be well-defined, possess a well-known shape, and always be validated, ensuring that digital resources and capabilities are what t...
Onboarding is Always as Easy as Possible
API operations is made easier by making common elements like documentation, authentication, SDKs easy to find and available as just a couple of simple steps that API consumers can follow when it co...
Operations Must Always Be Secure
Individual API operations should always be properly secured during design, develop, and run-time, making sure data, credentials, logs, and all other related resources are properly secured and opera...
Operations Must Be Useful and Consistent
All individual API operations must be useful and follow consistent Internet, industry, and enterprise standards, providing a simple and relevant HTTP API operation that does one thing and does it w...
