Transitioning from API discovery to integration as a consumer requires a well-defined and streamlined API onboarding process. Onboarding begins with discovery and relies heavily on clear documentation. However, other factors—such as account creation, authentication, SDK availability, and supporting resources—also play a critical role. API producers should regularly adopt the perspective of their consumers to experience onboarding through their customers eyes. Refining the API onboarding experience takes effort. It’s easy to either overlook critical steps or introduce unnecessary complexity. Ideally, the process should be self-service and require as few steps as possible to move from discovery to a 'hello world' first API call. Lessons about what works—or doesn’t—can often be drawn from the onboarding experiences of competitors and complementary services within your industry.
Onboarding
Properties
Policies
API Education and Enablement
Require that an API invests in educating and enabling its consumers through tutorials, guides, and clear explanations of not just how it works but why. Most friction around APIs comes from gaps in ...
Metadata for APIs
Unique identifier, name, description, tags, and other metadata for the API that defines the purpose of each individual API, and how it benefits API producer and consumers, establishing the base of ...
URL for APIs.json Contracts
Providing the valid URL for the APIs.json contract, identifying the source of the contract which may or may not be where it is found, helping make contract authoritative.
Base URL for API
Providing a valid URL to the base for an API that is designed for machines to use when making call to an API by an consumer.
Metadata for APIs.json Contracts
Unique identifier, name, description, tags, and other metadata for the contract that defines the purpose of the API Contract, and how it benefits API producer and consumers, establishing the base o...
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...
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...
Localization (Experience)
Require that APIs serving a global audience localize the things developers and end users actually experience, from documentation and portal content to error messages, currencies, and date and time ...
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.
Human URL for APIs.json Contract
Providing a valid URL to a landing page for the API that is designed for humans to use when learning more about an API.
API Licensing
Publishing a license for the interface, client code, server code, and data to ensure consumers understand the legal implications of using the API, code, and data into their own applications and int...
Login for APIs
Providing a way to login and gain access to an API, offering a simple human-readable URL to the login page, or ideally some sort of automated login process that allows access with as few clicks and...
Servers (OpenAPI)
Require that every OpenAPI definition declares its servers, the concrete base URLs where the API actually lives, ideally with an entry for each environment so production and sandbox are both discov...
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 ...
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 ...
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...
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...
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 Authentication Is Standardized
All APIs must use standardized authentication mechanisms including OAuth, JWT, and API keys with properly defined scopes, ensuring that security is consistently implemented and that consumers have ...
API Errors Are Standardized and Informative
All API error responses must follow standardized formats like RFC 7807 Problem Details, providing consistent error codes, human-readable messages, and correlation IDs that enable consumers to progr...
API Info and Metadata Is Complete and Accurate
All OpenAPI definitions must have complete info objects including title, description, version, contact information, license, and terms of service, providing both humans and machines with the contex...
API Parameters Are Well-Defined and Consistent
All API parameters must have clear names, descriptions, types, and constraints following consistent casing and naming conventions, with reusable parameters centralized in OpenAPI components to redu...
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 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 are Defined as API Contracts
All APIs are defined as API contracts so that we can align both the business and technology of delivering consistent high quality APIs, employing source control to manage the technical, but also th...
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 Legally Covered
All APIs must be reviewed by legal council and posses terms of service, privacy policy, licensing, and other regulatory and compliance requirements, making sure all the legal bases are covered bef...
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 Educate and Enable Consumers
Most of the friction around APIs comes from gaps in understanding, not gaps in technology. I believe API operations have a responsibility to educate and enable the people who use them, through tuto...
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 Have Clear Business Models
All APIs must have defined business models that articulate the value exchange between producer and consumer, including pricing tiers, plan features, rate limits, and metrics, ensuring that APIs are...
APIs Have One Click Access
All APIs possess a URL for humans to follow when engaging as well as the base path URL for machines to use when calling each API, ensuring that the front door for API operations within this domain ...
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 Possess Informative Metadata
All APIs possess metadata that is relevant to what APIs do, but also how they can be used in business by API consumers, and metadata helps ensure that the front door for API operations within this ...
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...
