Gaining the necessary access to effectively use an API is often more challenging than it appears. Intentional and unintentional barriers can create friction in discovering and onboarding with an API. Issues such as incomplete documentation and complex authentication processes frequently hinder adoption. These challenges often reflect the business dynamics and internal politics of making APIs available to teams, partners, and third-party developers. While API access may seem straightforward to the developers who created it—or to those accustomed to high-friction onboarding—it often overlooks critical steps that could simplify the process for others. Improving the API access experience can be as simple as providing clearer instructions, maintaining regular communication, and adopting the perspective of an API consumer. By walking through your own APIs or evaluating competitors’ offerings, you can identify opportunities to streamline access and improve usability.
Access
Policies
Agent-Scoped Authentication
I require that APIs support authentication credentials scoped specifically to agents, so that an autonomous consumer acts under its own narrowly-bound identity with least-privilege scopes rather th...
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.
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.
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...
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...
Privacy Policy
Publishing a privacy policy covering the producer and consumers of an API, as well as end-users of applications, adding to the legal resources that are available to 3rd party developers when puttin...
Authorization (Security)
Require that every API defines and enforces authorization explicitly, so I want each operation to declare what scopes, roles, or permissions it demands and to check them on every request, not just ...
CORS (Security)
Require that every browser-facing API sets a deliberate, least-privilege CORS policy, so I want explicit allowed origins, methods, and headers rather than a lazy wildcard slapped on to make an erro...
Security
Providing an overview of security practices for an API, including details covered as part of authentication and access management, but also security testing and certifications that matter to API co...
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...
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 Authorization Is Properly Defined and Enforced
All APIs must have clearly defined authorization models that control what authenticated consumers can access and perform, using role-based or attribute-based access control to ensure that permissio...
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 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 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 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...
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...
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...
