Self-service is the experience of a consumer being able to discover, access, and integrate an API without having to talk to a human. Portals, sign-up flows, documentation, and keys let developers get to their first successful call on their own schedule. Self-service is what lets an API scale its adoption beyond the capacity of any sales or support team. I believe self-service is one of the defining characteristics of a mature API operation. Every barrier that forces a consumer to wait on a person is a place where adoption stalls and momentum is lost. The best API providers make it possible to go from curiosity to production entirely on your own, and reserve human touch for where it genuinely adds value.
Self-Service
Policies
Blog Feeds
A blog RSS or Atom feed provides a simple way to syndicate information and updates about APIs with producers and consumers, allowing it to be pushed out to where they are located and regularly cons...
Blogs
A blog helps provide a regular channel for publishing relevant stories and information for both producers and consumers of an API, providing a simple, informative, and recurring way to stay in enga...
API Catalog (Experience)
Require that every API is registered in a central, searchable catalog with enough metadata that a developer can find it, understand it, and decide to use it without asking anyone. I care deeply abo...
Interactive Documentation (Experience)
Require that every API ships interactive documentation generated from its contract, where a developer can read the operations, see the schemas, and make a real call right from the page. I have beli...
Sandbox (Experience)
Require that every API offers a sandbox environment with test credentials and safe, representative data so a developer can experiment fully before touching production. I champion sandboxes because ...
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...
GitHub Organizations
A GitHub organization provides a dedicated workspaces for teams to produce APIs, organize all the API contracts in motion, and leverage source countrol, CI/CD, teams, and other resources provided b...
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.
OpenAPI
A machine-readable OpenAPI using the most recent version of the API specification, describing the surface area of each API, which is then used to render the human-readable documentation, and other ...
Portals
Dedicated developer portals for an API provide a way to make documentation, sign-up, getting started, plans, SDKs, and other resources API consumers need more easily accessible publicly or privatel...
Postman Collection
A machine-readable Postman Collection describing the surface area of the API contract or providing more modular and executable representations of portions of the API contract. - Postman - Executable
Postman Workspace
A Postman Workspace provides a dedicated space to manage API contracts within a domain, complimenting other types of workspaces, allowing for private, partner, and public workspaces to exist for ma...
SDKs
Offering software development kits, or SDKs for an API, handling authentication, and working across all available API operations in a variety of relevant programming languages to the targeted consu...
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...
Videos
Videos offer an engaging way to provide information and updates with producers nad consumers of APIs, demonstrating how an API can be used, providing webinars, workshops, and other useful videos ab...
Strategies
API Contracts Are Validated
All APIs must have a link to the evidence of the contract validation for business and technical contracts, allowing any stakeholder to review the details of the contract, as well as the rules appli...
API Delivery Is Fast and Design-First
API delivery must follow a design-first approach with mock servers, contract testing, and schema registries that enable parallel development, allowing consumers to begin integration before implemen...
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 Always Have Well-Defined Owners and Stakeholders
Each API should ideally have a dedicated product as well as an engineering owner, with other stakeholders across the API lifecycle defined in an easy to access human readable location, but also def...
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 Defined by Technical Contracts
All APIs must have machine-readable artifacts that defines the technical surface area of each API being made available to API consumers, utilizing open-source community specifications like OpenAPI ...
APIs Are Discoverable Through a Central Catalog
All APIs must be registered in a central catalog or registry with consistent metadata, tags, and descriptions, ensuring that producers and consumers can find existing APIs before building new ones,...
APIs Are Interoperable Across Systems
All APIs must prioritize interoperability by using standard media types, hypermedia link relations, and well-known specifications, enabling consumers to integrate multiple APIs together and reducin...
APIs Are Made Available Through a Platform Gateway
All APIs must be deployed through a common platform gateway established for the domain, line of business, or team, leveraging development, staging, and production environments, and a common set of ...
APIs Are Part of Regular Active Communication
All APIs are considered and included as part of regular internal and external communication channels, sharing road maps, change logs, blog posts, videos, and other relevant information that produce...
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 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 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 Operations Possess Dedicated Workspaces
API operations should provide dedicated workspace for domains, lines of business, and teams who are producing APIs, providing a dedicated location where work, collaboration, and automation can occu...
APIs Work Across Multiple Programming Languages
All APIs should have SDK and other client or server code available in multiple programming languages used by targeted API consumers for known business use cases, making it as simple as possible for...
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...
