[{"name":"Descriptions for APIs","slug":"api-metadata-descriptions","description":"I can't tell you how many APIs I come across that have no description or just a couple words that tell you nothing. A good description helps consumers understand what an API does and why they should care about it from a business perspective.","scope":"API Contract","property":"description","type":"I can't tell you how many APIs I come across that have no description or just a couple words that tell you nothing. A good description helps consumers understand what an API does and why they should care about it from a business perspective.","guidance":"apis/descriptions","image":"/images/descriptions.png","tags":["APIs","Discovery"],"rules":["apis-json-apis-description-info"],"stages":["Define","Default"],"research":null,"strategies":["apis-are-discoverable-through-a-central-catalog"],"experiences":["Discovery","Alignment","Communication","Onboarding"],"properties":["About"],"author":"Kin Lane"},{"name":"Images for APIs","slug":"api-metadata-images","description":"Images seem like a small thing, but when you are browsing through a catalog of hundreds of APIs, having a visual identity for each one makes a real difference in how discoverable and memorable they become.","scope":"API Contract","property":"image","type":"Images seem like a small thing, but when you are browsing through a catalog of hundreds of APIs, having a visual identity for each one makes a real difference in how discoverable and memorable they become.","guidance":"apis/images","image":"/images/images.png","tags":["APIs","Discovery"],"rules":["apis-json-apis-image-info"],"stages":["Define"],"research":null,"strategies":["apis-are-discoverable-through-a-central-catalog"],"experiences":["Discovery","Alignment","Communication","Onboarding"],"properties":["About"],"author":"Kin Lane"},{"name":"Names for APIs","slug":"api-metadata-names","description":"The name of your API is the first thing anyone sees. If it is vague or overly technical, people move on. A clear, concise name sets the right expectation about what the API does and the scope it covers.","scope":"API Contract","property":"name","type":"The name of your API is the first thing anyone sees. If it is vague or overly technical, people move on. A clear, concise name sets the right expectation about what the API does and the scope it covers.","guidance":"apis/names","image":"/images/names.png","tags":["APIs","Discovery"],"rules":["apis-json-apis-name-info"],"stages":["Define","Default"],"research":null,"strategies":["apis-are-discoverable-through-a-central-catalog"],"experiences":["Discovery","Alignment","Communication","Onboarding"],"properties":["About"],"author":"Kin Lane"},{"name":"Tags for APIs","slug":"api-metadata-tags","description":"Tags are one of those simple building blocks that do a lot of heavy lifting. They give your APIs a bounded context, help organize things by domain, and make it way easier for people to find what they are looking for.","scope":"API Contract","property":"tags","type":"Tags are one of those simple building blocks that do a lot of heavy lifting. They give your APIs a bounded context, help organize things by domain, and make it way easier for people to find what they are looking for.","guidance":"apis/tags","image":"/images/tags.png","tags":["APIs","Discovery"],"rules":["apis-json-apis-tags-info","apis-json-apis-tags-upper-case-error","apis-json-apis-tags-upper-case-info"],"stages":["Define","Default"],"research":null,"strategies":["apis-are-discoverable-through-a-central-catalog"],"experiences":["Discovery","Alignment","Communication","Onboarding"],"properties":["About"],"author":"Kin Lane"},{"name":"Unique Identifiers for APIs","slug":"api-metadata-unique-identifiers","description":"Every API needs a unique identifier. Without one, you can't reliably reference it in discovery, automation, or governance. It is the key that ties everything together across the contract.","scope":"API Contract","property":"aid","type":"Every API needs a unique identifier. Without one, you can't reliably reference it in discovery, automation, or governance. It is the key that ties everything together across the contract.","guidance":"apis/unique-identifiers","image":"/images/unique-identifiers.png","tags":["APIs","Discovery"],"rules":["apis-json-apis-aid-error","apis-json-apis-aid-info"],"stages":["Define","Default"],"research":null,"strategies":["apis-are-discoverable-through-a-central-catalog"],"experiences":["Discovery","Alignment","Communication","Onboarding"],"properties":["About"],"author":"Kin Lane"},{"name":"Metadata for APIs","slug":"api-metadata","description":"Metadata is the foundation of your API contract. The name, description, tags, and identifiers tell producers and consumers what this API is about and why it exists. Without solid metadata, everything else falls apart.","scope":"API Contract","property":"none","type":"Metadata is the foundation of your API contract. The name, description, tags, and identifiers tell producers and consumers what this API is about and why it exists. Without solid metadata, everything else falls apart.","guidance":"apis/metadata","image":"/images/meta-data.png","tags":["Metadata"],"policies":["api-metadata-unique-identifiers","api-metadata-names","api-metadata-descriptions","api-metadata-images","api-metadata-tags"],"experiences":["Alignment","APIs","Communication","Discovery","Onboarding"],"stages":["Define"],"research":null,"strategies":["apis-are-discoverable-through-a-central-catalog","apis-possess-informative-metadata"],"properties":["About"],"author":"Kin Lane"},{"name":"Created Date for APIs.json Contracts","slug":"apis-json-created-info","description":"Knowing when an API contract was first created tells you a lot about its maturity. I look at this date to understand how long something has been in play and what kind of history it carries.","scope":"Business Contract","property":"created","type":"Knowing when an API contract was first created tells you a lot about its maturity. I look at this date to understand how long something has been in play and what kind of history it carries.","guidance":"change/created","image":"/images/created-date.png","tags":["Dates","Change"],"experiences":["Alignment","Change","Communication","Consistency","Quality","Reliability"],"rules":["apis-json-created-info"],"stages":["Define","Default"],"research":null,"strategies":["api-change-is-relative-to-operational-change"],"author":"Kin Lane"},{"name":"Modified Date for APIs.json Contracts","slug":"apis-json-modified-info","description":"The modified date is one of the quickest signals I check. If an API contract has not been touched in a long time, that tells me something. Velocity and stagnation both show up here.","scope":"Business Contract","property":"modified","type":"The modified date is one of the quickest signals I check. If an API contract has not been touched in a long time, that tells me something. Velocity and stagnation both show up here.","guidance":"change/modified","image":"/images/modified-date.png","tags":["Dates","Change"],"experiences":["Alignment","Change","Communication","Consistency","Quality","Reliability"],"rules":["apis-json-modified-info"],"stages":["Define","Design","Develop","Default"],"research":null,"strategies":["api-change-is-relative-to-operational-change"],"author":"Kin Lane"},{"name":"URL for APIs.json Contracts","slug":"apis-json-url-info","description":"Every API contract needs a valid URL that points back to its source of truth. This is how you make a contract authoritative and verifiable, not just a copy floating around somewhere.","scope":"Business Contract","property":"url","type":"Every API contract needs a valid URL that points back to its source of truth. This is how you make a contract authoritative and verifiable, not just a copy floating around somewhere.","guidance":"contracts/apis-json-url","image":"/images/url.png","tags":["URLs"],"experiences":["Onboarding","Access"],"rules":["apis-json-url-info"],"stages":["Define","Default"],"research":null,"strategies":["apis-have-one-click-access"],"author":"Kin Lane"},{"name":"JWT (Authentication)","slug":"authentication-jwt","description":"JWT is a common pattern I see across the API landscape for authentication. Having a policy around how JWTs are used keeps things consistent and prevents teams from rolling their own approach.","scope":"","property":"","type":"JWT is a common pattern I see across the API landscape for authentication. Having a policy around how JWTs are used keeps things consistent and prevents teams from rolling their own approach.","guidance":"","image":"/images/jwt.png","tags":["Policies","3rd-Party","Producers"],"stages":["Define"],"research":null,"strategies":["api-authentication-is-standardized","api-authorization-is-properly-defined-and-enforced"],"experiences":["Security","Access","Trust","Onboarding"],"properties":["Authentication"],"author":"Kin Lane"},{"name":"Keys (Authentication)","slug":"authentication-keys","description":"API keys are the most basic building block of API authentication. A policy here makes sure keys are handled consistently and not just thrown around without any standards in place.","scope":"","property":"","type":"API keys are the most basic building block of API authentication. A policy here makes sure keys are handled consistently and not just thrown around without any standards in place.","guidance":"","image":"/images/keys.png","tags":["Policies","3rd-Party","Producers"],"stages":["Define","Default"],"research":null,"strategies":["api-authentication-is-standardized","api-authorization-is-properly-defined-and-enforced"],"experiences":["Security","Access","Trust","Onboarding"],"properties":["Authentication"],"author":"Kin Lane"},{"name":"OAuth (Authentication)","slug":"authentication-oauth","description":"OAuth is the standard I see most often when APIs need proper authorization flows. Having a clear policy around OAuth usage keeps the implementation consistent and reduces security surface area.","scope":"","property":"","type":"OAuth is the standard I see most often when APIs need proper authorization flows. Having a clear policy around OAuth usage keeps the implementation consistent and reduces security surface area.","guidance":"","image":"/images/oauth.png","tags":["Policies","3rd-Party","Producers"],"stages":["Define"],"research":null,"strategies":["api-authentication-is-standardized","api-authorization-is-properly-defined-and-enforced"],"experiences":["Security","Access","Trust","Onboarding"],"properties":["Authentication","OAuthScopes"],"author":"Kin Lane"},{"name":"Scopes (Authentication)","slug":"authentication-scopes","description":"OAuth scopes are where the rubber meets the road on access control. Getting scopes right means consumers understand exactly what they are asking for and what they are getting.","scope":"","property":"","type":"OAuth scopes are where the rubber meets the road on access control. Getting scopes right means consumers understand exactly what they are asking for and what they are getting.","guidance":"","image":"/images/scopes.png","tags":["Properties","3rd-Party"],"stages":["Define"],"research":null,"strategies":["api-authentication-is-standardized","api-authorization-is-properly-defined-and-enforced"],"experiences":["Security","Access","Trust","Onboarding"],"properties":["OAuthScopes"],"author":"Kin Lane"},{"name":"Authentication","slug":"security-authentication","description":"Authentication details should always travel with the API contract. I have seen too many situations where developers can find the docs but have no idea how to actually authenticate. That information needs to be front and center.","scope":"","property":"","type":"Authentication details should always travel with the API contract. I have seen too many situations where developers can find the docs but have no idea how to actually authenticate. That information needs to be front and center.","guidance":"","image":"/images/authentication.png","tags":["Policies","3rd-Party","Producers"],"stages":["Define"],"research":null,"strategies":["api-authentication-is-standardized","api-authorization-is-properly-defined-and-enforced"],"experiences":["Security","Access","Trust","Onboarding"],"properties":["Authentication"],"author":"Kin Lane"},{"name":"Base URL for API","slug":"base-url","description":"The base URL is the machine-readable address consumers use to make calls. Getting this right and keeping it stable is a fundamental part of the API contract that too many teams overlook.","scope":"API Contract","property":"baseURL","type":"The base URL is the machine-readable address consumers use to make calls. Getting this right and keeping it stable is a fundamental part of the API contract that too many teams overlook.","guidance":"apis/base-url","image":"/images/base-url.png","tags":["URLs"],"experiences":["Onboarding","Access"],"rules":["apis-json-apis-baseURL-error","apis-json-apis-baseURL-info"],"stages":["Define","Default"],"research":null,"strategies":["apis-have-one-click-access"],"author":"Kin Lane"},{"name":"Blog Feeds","slug":"blog-feeds","description":"Blog feeds let you push updates out to where producers and consumers already are. RSS and Atom are old-school building blocks, but they still work well for syndicating API news without requiring people to visit a website.","scope":"Business Contract","property":"none","type":"Blog feeds let you push updates out to where producers and consumers already are. RSS and Atom are old-school building blocks, but they still work well for syndicating API news without requiring people to visit a website.","guidance":"communication/blog-feeds","image":"/images/blog-feeds.png","tags":["Blog","Stories","Updates"],"experiences":["Alignment","Change","Communication","Consistency","Discovery","Self-Service"],"rules":["apis-json-apis-properties-blog-feed-info"],"stages":["Define"],"research":null,"strategies":["apis-are-part-of-regular-active-communication"],"properties":["BlogFeeds"],"author":"Kin Lane"},{"name":"Blogs","slug":"blogs","description":"A blog gives you a steady channel for telling stories about your API. It keeps producers and consumers engaged with regular updates and creates a narrative around what is happening and why it matters.","scope":"Business Contract","property":"none","type":"A blog gives you a steady channel for telling stories about your API. It keeps producers and consumers engaged with regular updates and creates a narrative around what is happening and why it matters.","guidance":"communication/blog","image":"/images/blogs.png","tags":["Blog","Stories","Updates"],"experiences":["Alignment","Change","Communication","Consistency","Discovery","Self-Service"],"rules":["apis-json-apis-properties-blog-feed-info"],"stages":["Production","Default"],"research":null,"strategies":["apis-are-part-of-regular-active-communication"],"properties":["Blog","Blogs"],"author":"Kin Lane"},{"name":"Business Contract Validator","slug":"business-contract-validator","description":"Validation is where governance becomes real. Having a validator linked to each business contract lets you run linting rules and see exactly where things stand against your policies.","scope":"Business Contract","property":"none","type":"Validation is where governance becomes real. Having a validator linked to each business contract lets you run linting rules and see exactly where things stand against your policies.","guidance":"validator/overview","image":"/images/validator.png","tags":["Validation","Business"],"rules":["apis-json-apis-properties-apis-json-validator-info"],"stages":["Define"],"research":null,"strategies":["api-contracts-are-validated"],"experiences":["Quality","Consistency","Automation"],"author":"Kin Lane"},{"name":"Change Log Date","slug":"change-log-date","description":"Every change log entry needs a date. Without it, you lose the timeline of what happened and when, which makes it really hard to understand the evolution of an API.","scope":"","property":"","type":"Every change log entry needs a date. Without it, you lose the timeline of what happened and when, which makes it really hard to understand the evolution of an API.","guidance":"","image":"/images/dates.png","tags":["Properties","3rd-Party"],"research":null,"experiences":["Change","Communication","Provenance"],"strategies":["change-is-actively-managed-for-each-api","api-change-is-relative-to-operational-change"],"properties":["ChangeLog"],"author":"Kin Lane"},{"name":"Change Log Details","slug":"change-log-details","description":"The description in a change log entry tells the story of what actually changed. This is where you communicate the why behind a modification, not just the what.","scope":"","property":"","type":"The description in a change log entry tells the story of what actually changed. This is where you communicate the why behind a modification, not just the what.","guidance":"","image":"/images/descriptions.png","tags":["Properties","3rd-Party"],"research":null,"experiences":["Change","Communication","Provenance"],"strategies":["change-is-actively-managed-for-each-api","api-change-is-relative-to-operational-change"],"properties":["ChangeLog"],"author":"Kin Lane"},{"name":"Change Log Title","slug":"change-log-title","description":"A change log title gives each entry a clear label. It is the first thing people scan when trying to figure out what has been happening with an API over time.","scope":"","property":"","type":"A change log title gives each entry a clear label. It is the first thing people scan when trying to figure out what has been happening with an API over time.","guidance":"","image":"/images/names.png","tags":["Properties","3rd-Party"],"research":null,"experiences":["Change","Communication","Provenance"],"strategies":["change-is-actively-managed-for-each-api","api-change-is-relative-to-operational-change"],"properties":["ChangeLog"],"author":"Kin Lane"},{"name":"Change Log Version","slug":"change-log-version","description":"Tying each change log entry to a version number connects the dots between what changed and which release it shipped in. This is how consumers track what is relevant to them.","scope":"","property":"","type":"Tying each change log entry to a version number connects the dots between what changed and which release it shipped in. This is how consumers track what is relevant to them.","guidance":"","image":"/images/versions.png","tags":["Properties","3rd-Party"],"research":null,"experiences":["Change","Communication","Provenance"],"strategies":["change-is-actively-managed-for-each-api","api-change-is-relative-to-operational-change"],"properties":["ChangeLog"],"author":"Kin Lane"},{"name":"Change Log","slug":"change-log","description":"A change log is essential for tracking everything that has been added, updated, or removed. I look at change logs as the honest record of an API's evolution that builds trust with consumers.","scope":"Business Contract","property":"none","type":"A change log is essential for tracking everything that has been added, updated, or removed. I look at change logs as the honest record of an API's evolution that builds trust with consumers.","guidance":"change/change-log","image":"/images/change-logs.png","tags":["GitHub","Issues","Labels"],"experiences":["Alignment","Change","Communication","Consistency","Quality","Reliability"],"rules":["apis-json-apis-properties-change-log-info"],"stages":["Production","Default"],"research":null,"strategies":["api-change-is-relative-to-operational-change","apis-are-gracefully-deprecated-and-retired","breaking-changes-are-prevented-or-carefully-managed","change-is-actively-managed-for-each-api"],"properties":["ChangeLog"],"author":"Kin Lane"},{"name":"Descriptions for APIs.json Contracts","slug":"contract-metadata-descriptions","description":"API contracts need good descriptions just like the APIs themselves do. A solid description of the contract gives stakeholders the context they need to understand what they are looking at.","scope":"Business Contract","property":"description","type":"API contracts need good descriptions just like the APIs themselves do. A solid description of the contract gives stakeholders the context they need to understand what they are looking at.","guidance":"contracts/descriptions","image":"/images/descriptions.png","tags":["Contracts","Discovery"],"rules":["apis-json-description-info"],"stages":["Define","Default"],"research":null,"experiences":["Discovery","Alignment","Communication"],"strategies":["apis-are-defined-as-api-contracts"],"author":"Kin Lane"},{"name":"Images for APIs.json Contracts","slug":"contract-metadata-images","description":"Adding images to your API contract metadata might seem minor, but it makes APIs more recognizable across portals, docs, and catalogs. Visual identity matters at scale.","scope":"Business Contract","property":"image","type":"Adding images to your API contract metadata might seem minor, but it makes APIs more recognizable across portals, docs, and catalogs. Visual identity matters at scale.","guidance":"contracts/images","image":"/images/images.png","tags":["Contracts","Discovery"],"rules":["apis-json-image-info"],"stages":["Define"],"research":null,"experiences":["Discovery","Alignment","Communication"],"strategies":["apis-are-defined-as-api-contracts"],"author":"Kin Lane"},{"name":"Names for APIs.json Contracts","slug":"contract-metadata-names","description":"Naming your API contract well is about defining scope. A clear, descriptive name tells people exactly what bundle of APIs they are looking at and what domain it covers.","scope":"Business Contract","property":"name","type":"Naming your API contract well is about defining scope. A clear, descriptive name tells people exactly what bundle of APIs they are looking at and what domain it covers.","guidance":"contracts/names","image":"/images/names.png","tags":["Contracts","Discovery"],"rules":["apis-json-name-info"],"stages":["Define","Default"],"research":null,"experiences":["Discovery","Alignment","Communication"],"strategies":["apis-are-defined-as-api-contracts"],"author":"Kin Lane"},{"name":"Tags for APIs.json Contracts","slug":"contract-metadata-tags","description":"Tags on your API contracts serve the same purpose as tags on individual APIs. They create bounded context, organize by domain, and make discovery possible at the contract level.","scope":"Business Contract","property":"tags","type":"Tags on your API contracts serve the same purpose as tags on individual APIs. They create bounded context, organize by domain, and make discovery possible at the contract level.","guidance":"contracts/tags","image":"/images/tags.png","tags":["Contracts","Discovery"],"rules":["apis-json-tags-info","apis-json-tags-upper-case-error","apis-json-tags-upper-case-info"],"stages":["Define","Default"],"research":null,"experiences":["Discovery","Alignment","Communication"],"strategies":["apis-are-defined-as-api-contracts"],"author":"Kin Lane"},{"name":"Unique Identifiers for APIs.json Contracts","slug":"contract-metadata-unique-identifiers","description":"Unique identifiers for your API contracts and the APIs they contain give you the reference points you need for automation, discovery, and governance at scale.","scope":"Business Contract","property":"aid","type":"Unique identifiers for your API contracts and the APIs they contain give you the reference points you need for automation, discovery, and governance at scale.","guidance":"contracts/unique-identifiers","image":"/images/unique-identifiers.png","tags":["Contracts","Discovery"],"rules":["apis-json-specification-aid-info"],"stages":["Define","Default"],"research":null,"experiences":["Discovery","Alignment","Communication"],"strategies":["apis-are-defined-as-api-contracts"],"author":"Kin Lane"},{"name":"Metadata for APIs.json Contracts","slug":"contract-metadata","description":"The metadata on your API contract is the first handshake with anyone who encounters it. The identifier, name, description, and tags establish what this agreement is about and who it serves.","scope":"Business Contract","property":"none","type":"The metadata on your API contract is the first handshake with anyone who encounters it. The identifier, name, description, and tags establish what this agreement is about and who it serves.","guidance":"contracts/metadata","image":"/images/meta-data.png","tags":["Contracts","Discovery"],"policies":["contract-metadata-unique-identifiers","contract-metadata-names","contract-metadata-descriptions","contract-metadata-images","contract-metadata-tags"],"experiences":["Alignment","Products","Communication","Discovery","Onboarding"],"stages":["Define"],"research":null,"strategies":["apis-are-defined-as-api-contracts","apis-are-discoverable-through-a-central-catalog"],"author":"Kin Lane"},{"name":"Documentation Examples","slug":"documentation-examples","description":"Examples are where documentation goes from theoretical to practical. Showing real request and response variations helps developers understand what is actually possible with an API.","scope":"Business Contract","property":"none","type":"Examples are where documentation goes from theoretical to practical. Showing real request and response variations helps developers understand what is actually possible with an API.","guidance":"documentation/examples","image":"/images/examples.png","tags":["Policies","3rd-Party","Producers"],"stages":["Beta"],"research":null,"strategies":["apis-deliver-an-exceptional-developer-experience"],"experiences":["Onboarding","Developer Experience","Quality","Self-Service"],"properties":["Documentation","Examples"],"author":"Kin Lane"},{"name":"Documentation Paths","slug":"documentation-paths","description":"Clean, intuitive paths in your documentation make a big difference. If consumers can not quickly scan and understand the URL patterns, they are going to struggle with the rest.","scope":"Business Contract","property":"none","type":"Clean, intuitive paths in your documentation make a big difference. If consumers can not quickly scan and understand the URL patterns, they are going to struggle with the rest.","guidance":"documentation/paths","image":"/images/paths.png","tags":["Policies","3rd-Party","Producers"],"stages":["Beta"],"research":null,"strategies":["apis-deliver-an-exceptional-developer-experience"],"experiences":["Onboarding","Developer Experience","Quality","Self-Service"],"properties":["Documentation"],"author":"Kin Lane"},{"name":"Documentation Request Bodies","slug":"documentation-request-bodies","description":"Request bodies are where consumers need the most hand-holding. Clear details and examples for POST and PUT payloads prevent a lot of frustration and support tickets.","scope":"Business Contract","property":"none","type":"Request bodies are where consumers need the most hand-holding. Clear details and examples for POST and PUT payloads prevent a lot of frustration and support tickets.","guidance":"documentation/request-bodies","image":"/images/request-bodies.png","tags":["Policies","3rd-Party","Producers"],"stages":["Beta"],"research":null,"strategies":["apis-deliver-an-exceptional-developer-experience"],"experiences":["Onboarding","Developer Experience","Quality","Self-Service"],"properties":["Documentation"],"author":"Kin Lane"},{"name":"Documentation Responses","slug":"documentation-responses","description":"Every response needs a complete example in the docs, including the unhappy paths. Developers need to know what success looks like and what happens when things go wrong.","scope":"Business Contract","property":"none","type":"Every response needs a complete example in the docs, including the unhappy paths. Developers need to know what success looks like and what happens when things go wrong.","guidance":"documentation/responses","image":"/images/responses.png","tags":["Policies","3rd-Party","Producers"],"stages":["Beta"],"research":null,"strategies":["apis-deliver-an-exceptional-developer-experience"],"experiences":["Onboarding","Developer Experience","Quality","Self-Service"],"properties":["Documentation"],"author":"Kin Lane"},{"name":"Documentation Schema","slug":"documentation-schema","description":"Documenting your schema objects is how you give consumers the full picture of what data flows through the API. JSON Schema representations make this concrete and referenceable.","scope":"Business Contract","property":"none","type":"Documenting your schema objects is how you give consumers the full picture of what data flows through the API. JSON Schema representations make this concrete and referenceable.","guidance":"documentation/schema","image":"/images/schema.png","tags":["Policies","3rd-Party","Producers"],"stages":["Beta"],"research":null,"strategies":["apis-deliver-an-exceptional-developer-experience"],"experiences":["Onboarding","Developer Experience","Quality","Self-Service"],"properties":["Documentation"],"author":"Kin Lane"},{"name":"Documentation","slug":"documentation","description":"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 started.","scope":"Business Contract","property":"none","type":"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 started.","guidance":"documentation/overview","image":"/images/documentation.png","tags":["Documentation"],"experiences":["Alignment","Communication","Onboarding","Discovery","Simplicity","Consistency"],"rules":["apis-json-apis-properties-documentation-info"],"stages":["Beta","Default"],"research":null,"strategies":["apis-are-always-well-documented","apis-deliver-an-exceptional-developer-experience"],"properties":["Documentation"],"author":"Kin Lane"},{"name":"Environments","slug":"environments","description":"Having clear development, staging, and production environments available in a machine-readable way lets consumers and automation navigate between environments without guessing.","scope":"Business Contract","property":"none","type":"Having clear development, staging, and production environments available in a machine-readable way lets consumers and automation navigate between environments without guessing.","guidance":"gateways/overview","image":"/images/gateways.png","tags":["Environments"],"rules":["apis-json-apis-properties-environments-production-info","apis-json-apis-properties-environments-staging-info"],"stages":["Development"],"research":null,"strategies":["apis-are-made-available-through-a-platform-gateway"],"experiences":["Access","Onboarding","Automation"],"properties":["StagingEnvironment"],"author":"Kin Lane"},{"name":"Feedback Issues","slug":"feedback-issues","description":"Git issues are a straightforward way to collect feedback on API contracts. They create a public record of the conversation and keep feedback tied to the source of truth.","scope":"Business Contract","property":"none","type":"Git issues are a straightforward way to collect feedback on API contracts. They create a public record of the conversation and keep feedback tied to the source of truth.","guidance":"","image":"/images/issues.png","tags":["Policies","3rd-Party","Producers"],"rules":["apis-json-apis-properties-feedback-issues-info"],"stages":["Define"],"research":null,"experiences":["Support","Communication","Alignment"],"strategies":["apis-must-be-supported-and-have-feedback-loops"],"properties":["FeedbackGitHubIssues"],"author":"Kin Lane"},{"name":"Feedback","slug":"feedback","description":"Feedback loops are how you learn what is actually working and what is not. Making it easy for consumers and stakeholders to share their thoughts on the business and technical details of an API contract is how you improve.","scope":"Business Contract","property":"none","type":"Feedback loops are how you learn what is actually working and what is not. Making it easy for consumers and stakeholders to share their thoughts on the business and technical details of an API contract is how you improve.","guidance":"","image":"/images/feedback.png","tags":["Support","3rd-Party","Producers"],"policies":["feedback-issues"],"stages":["Define","Default"],"research":null,"strategies":["api-development-is-collaborative-across-teams","apis-must-be-supported-and-have-feedback-loops"],"experiences":["Support","Communication","Alignment"],"properties":["FeedbackEmail","FeedbackGitHubIssues"],"author":"Kin Lane"},{"name":"Gateways","slug":"gateway","description":"Gateways are a central building block in the API landscape. Running APIs through a designated gateway gives you shared authentication, rate limiting, and all the operational capabilities that come with a managed platform.","scope":"Business Contract","property":"none","type":"Gateways are a central building block in the API landscape. Running APIs through a designated gateway gives you shared authentication, rate limiting, and all the operational capabilities that come with a managed platform.","guidance":"gateways/overview","image":"/images/gateways.png","tags":["Gateway"],"rules":["apis-json-apis-properties-gateway-info"],"stages":["Beta","Default"],"research":null,"strategies":["apis-are-made-available-through-a-platform-gateway","apis-are-protected-from-abuse-and-misuse"],"experiences":["Access","Security","Scalability"],"properties":["Gateway"],"author":"Kin Lane"},{"name":"Getting Started Authentication","slug":"getting-started-authentication","description":"The getting started experience needs to cover authentication clearly. If a new consumer can not figure out how to authenticate quickly, you have already lost them.","scope":"Business Contract","property":"none","type":"The getting started experience needs to cover authentication clearly. If a new consumer can not figure out how to authenticate quickly, you have already lost them.","guidance":"","image":"/images/authentication.png","tags":["Policies","3rd-Party","Producers"],"stages":["Beta"],"research":null,"strategies":["api-authentication-is-standardized","apis-deliver-an-exceptional-developer-experience"],"experiences":["Onboarding","Self-Service","Developer Experience"],"properties":["GettingStarted","Authentication"],"author":"Kin Lane"},{"name":"Getting Started Documentation","slug":"getting-started-documentation","description":"Pointing new consumers to your documentation is the first step in getting started. This is the entry point where they begin learning what the API does and how to use it.","scope":"Business Contract","property":"none","type":"Pointing new consumers to your documentation is the first step in getting started. This is the entry point where they begin learning what the API does and how to use it.","guidance":"","image":"/images/documentation.png","tags":["Policies","3rd-Party","Producers"],"stages":["Beta"],"research":null,"strategies":["apis-deliver-an-exceptional-developer-experience"],"experiences":["Onboarding","Self-Service","Developer Experience"],"properties":["GettingStarted","Documentation"],"author":"Kin Lane"},{"name":"Getting Started SDKs","slug":"getting-started-sdks","description":"Including SDKs in your getting started flow gives consumers a head start. Pointing them to client libraries and code they can use right away removes a lot of friction from onboarding.","scope":"Business Contract","property":"none","type":"Including SDKs in your getting started flow gives consumers a head start. Pointing them to client libraries and code they can use right away removes a lot of friction from onboarding.","guidance":"","image":"/images/sdks.png","tags":["Policies","3rd-Party","Producers"],"stages":["Beta"],"research":null,"strategies":["apis-deliver-an-exceptional-developer-experience"],"experiences":["Onboarding","Self-Service","Developer Experience"],"properties":["GettingStarted","SDKs"],"author":"Kin Lane"},{"name":"Getting Started","slug":"getting-started","description":"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 breaks adoption.","scope":"Business Contract","property":"none","type":"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 breaks adoption.","guidance":"onboarding/getting-started","image":"/images/getting-started.png","tags":["Business"],"experiences":["Communication","Consistency","Discovery","Onboarding","Self-Service","Simplicity"],"rules":["apis-json-apis-properties-getting-started-info"],"stages":["Beta","Default"],"research":null,"strategies":["apis-deliver-an-exceptional-developer-experience","onboarding-is-always-as-easy-as-possible"],"properties":["GettingStarted"],"author":"Kin Lane"},{"name":"GitHub Organization README","slug":"github-organization-readme","description":"A GitHub organization README gives you a landing page for your API workspace. It is where people land first and where all the API contracts within a domain should be findable and searchable.","scope":"Business Contract","property":"none","type":"A GitHub organization README gives you a landing page for your API workspace. It is where people land first and where all the API contracts within a domain should be findable and searchable.","guidance":"workspaces/github-organization-readme","image":"/images/readme.png","tags":["README"],"stages":["Define"],"research":null,"experiences":["Workspaces","Collaboration","Automation"],"strategies":["apis-operations-possess-dedicated-workspaces","api-development-is-collaborative-across-teams"],"properties":["GitHubOrganization"],"author":"Kin Lane"},{"name":"GitHub Organization Repositories","slug":"github-organization-repositories","description":"Repositories within a GitHub organization let you separate and organize API contracts by bounded context. This is how you keep things manageable as the number of APIs grows within a domain.","scope":"Business Contract","property":"none","type":"Repositories within a GitHub organization let you separate and organize API contracts by bounded context. This is how you keep things manageable as the number of APIs grows within a domain.","guidance":"workspaces/github-organization-repositories","image":"/images/teams.png","tags":["Teams"],"stages":["Define"],"research":null,"strategies":["api-development-is-collaborative-across-teams"],"experiences":["Workspaces","Collaboration","Automation"],"properties":["GitHubOrganization","GitHubRepository"],"author":"Kin Lane"},{"name":"GitHub Organization Teams","slug":"github-organization-teams","description":"GitHub teams let you define who has access to what. Managing people and permissions at the organization level is how you control access to repositories, contracts, and the API operations that flow through them.","scope":"Business Contract","property":"none","type":"GitHub teams let you define who has access to what. Managing people and permissions at the organization level is how you control access to repositories, contracts, and the API operations that flow through them.","guidance":"workspaces/github-organization-teams","image":"/images/teams.png","tags":["Teams"],"stages":["Define"],"research":null,"strategies":["api-development-is-collaborative-across-teams"],"experiences":["Workspaces","Collaboration","Automation"],"properties":["GitHubOrganization"],"author":"Kin Lane"},{"name":"GitHub Organizations","slug":"github-organization","description":"A GitHub organization is the workspace where API operations happen. Source control, CI/CD, teams, and collaboration all come together here as the backbone of how APIs get produced and managed.","scope":"Business Contract","property":"none","type":"A GitHub organization is the workspace where API operations happen. Source control, CI/CD, teams, and collaboration all come together here as the backbone of how APIs get produced and managed.","guidance":"workspaces/github-organization","image":"/images/github-organization.png","tags":["GitHub","Repositories","Source Control"],"experiences":["Access","Automation","Communication","Discovery","Onboarding","Self-Service","Workspaces","Collaboration"],"rules":["apis-json-apis-properties-github-organization-info"],"stages":["Define","Default"],"research":null,"strategies":["api-development-is-collaborative-across-teams","apis-operations-possess-dedicated-workspaces"],"properties":["GitHubOrganization"],"author":"Kin Lane"},{"name":"GitHub Repository","slug":"github-repository","description":"The GitHub repository is the single source of truth for an API contract. OpenAPI, road map, change log, support -- everything lives here, and it is where the real work of producing APIs happens.","scope":"Business Contract","property":"none","type":"The GitHub repository is the single source of truth for an API contract. OpenAPI, road map, change log, support -- everything lives here, and it is where the real work of producing APIs happens.","guidance":"repositories/github","image":"/images/repositories.png","tags":["GitHub","Repositories","Source Control"],"experiences":["Change","Consistency","Communication","Discovery","Quality","Reliability","Workspaces","Collaboration","Provenance"],"rules":["apis-json-apis-properties-github-repository-info"],"stages":["Define","Default"],"research":null,"strategies":["producing-apis-must-be-repeatable"],"properties":["GitHubRepository"],"author":"Kin Lane"},{"name":"API Governance Rules","slug":"governance-api-rules","description":"Spectral rules applied at the API level are where governance becomes automated. Linting OpenAPI contracts with these rules catches design inconsistencies before they make it to production.","scope":"Business Contract","property":"none","type":"Spectral rules applied at the API level are where governance becomes automated. Linting OpenAPI contracts with these rules catches design inconsistencies before they make it to production.","guidance":"governance/api-rules","image":"/images/rules.png","tags":["Governance"],"rules":["apis-json-apis-properties-openapi-rules-info"],"stages":["Define","Default"],"research":null,"strategies":["api-governance-is-automated-in-cicd"],"experiences":["Governance","Consistency","Quality","Alignment"],"properties":["ApiRules"],"author":"Kin Lane"},{"name":"API Lifecycle","slug":"governance-lifecycle","description":"Having a machine-readable schema of your API lifecycle gives everyone a shared understanding of the stages an API moves through. This is the common language that keeps teams aligned.","scope":"Business Contract","property":"none","type":"Having a machine-readable schema of your API lifecycle gives everyone a shared understanding of the stages an API moves through. This is the common language that keeps teams aligned.","guidance":"governance/lifecycle","image":"/images/lifecycle.png","tags":["Governance"],"rules":["apis-json-apis-properties-lifecycle-info"],"stages":["Define","Default"],"research":null,"strategies":["api-maturity-is-measured-and-improved"],"experiences":["Governance","Consistency","Quality","Alignment"],"properties":["Lifecycle"],"author":"Kin Lane"},{"name":"Operational Governance Rules","slug":"governance-operational-rules","description":"Operational rules lint the APIs.json business contract the same way API rules lint OpenAPI. This is how you govern the operational surface area around your APIs, not just the technical design.","scope":"Business Contract","property":"none","type":"Operational rules lint the APIs.json business contract the same way API rules lint OpenAPI. This is how you govern the operational surface area around your APIs, not just the technical design.","guidance":"governance/operational-rules","image":"/images/rules.png","tags":["Governance"],"rules":["apis-json-apis-properties-apis-json-rules-info"],"stages":["Define","Default"],"research":null,"strategies":["api-governance-is-automated-in-cicd"],"experiences":["Governance","Consistency","Quality","Alignment"],"properties":["OperationalRules"],"author":"Kin Lane"},{"name":"Governance Policies","slug":"governance-policies","description":"Policies are the bridge between business objectives and the rules that govern APIs. Making them human and machine-readable keeps governance aligned with what the business actually cares about.","scope":"Business Contract","property":"none","type":"Policies are the bridge between business objectives and the rules that govern APIs. Making them human and machine-readable keeps governance aligned with what the business actually cares about.","guidance":"governance/policies","image":"/images/policies.png","tags":["Governance"],"rules":["apis-json-apis-properties-policies-info"],"stages":["Define","Default"],"research":null,"strategies":["api-maturity-is-measured-and-improved"],"experiences":["Governance","Consistency","Quality","Alignment"],"properties":["Policies"],"author":"Kin Lane"},{"name":"Governance Vocabulary","slug":"governance-vocabulary","description":"A shared vocabulary across API operations prevents the kind of naming chaos I see everywhere. When everyone uses the same words the same way, APIs become more consistent and understandable.","scope":"Business Contract","property":"none","type":"A shared vocabulary across API operations prevents the kind of naming chaos I see everywhere. When everyone uses the same words the same way, APIs become more consistent and understandable.","guidance":"governance/vocabulary","image":"/images/lifecycle.png","tags":["Governance"],"rules":["apis-json-apis-properties-vocabulary-info"],"stages":["Define","Default"],"research":null,"experiences":["Governance","Consistency","Quality","Alignment"],"strategies":["apis-must-be-actively-governed","api-maturity-is-measured-and-improved"],"properties":["Vocabulary"],"author":"Kin Lane"},{"name":"Governance","slug":"governance","description":"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 APIs without slowing down.","scope":"Business Contract","property":"none","type":"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 APIs without slowing down.","guidance":"governance/overview","image":"/images/governance.png","tags":["Governance"],"policies":["governance-policies","governance-operational-rules","governance-api-rules","governance-lifecycle","governance-vocabulary"],"experiences":["Access","Alignment","Automation","Change","Communication","Consistency","Discovery","Legal","Onboarding","Quality","Reliability","Security","Self-Service","Simplicity","Governance","Collaboration","Trust"],"stages":["Define"],"research":null,"strategies":["apis-must-be-actively-governed"],"author":"Kin Lane"},{"name":"Business Guidance","slug":"guidance-business","description":"Business guidance gives API teams the context they need to make good decisions about the non-technical side of producing APIs. This is where business strategy meets API operations.","scope":"Business Contract","property":"none","type":"Business guidance gives API teams the context they need to make good decisions about the non-technical side of producing APIs. This is where business strategy meets API operations.","guidance":"","image":"/images/business.png","tags":["Policies","3rd-Party","Producers"],"stages":["Define"],"research":null,"experiences":["Onboarding","Quality","Governance"],"strategies":["apis-must-be-actively-governed"],"author":"Kin Lane"},{"name":"People Guidance","slug":"guidance-people","description":"People guidance helps teams navigate the human side of API operations. Roles, responsibilities, and collaboration patterns are just as important as the technical decisions.","scope":"Business Contract","property":"none","type":"People guidance helps teams navigate the human side of API operations. Roles, responsibilities, and collaboration patterns are just as important as the technical decisions.","guidance":"","image":"/images/people.png","tags":["Policies","3rd-Party","Producers"],"stages":["Define"],"research":null,"experiences":["Onboarding","Quality","Governance"],"strategies":["apis-must-be-actively-governed"],"author":"Kin Lane"},{"name":"Policy Guidance","slug":"guidance-policies","description":"Policy guidance explains the why behind each governance policy. Without guidance, policies just feel like rules being imposed from above rather than building blocks that help everyone.","scope":"Business Contract","property":"none","type":"Policy guidance explains the why behind each governance policy. Without guidance, policies just feel like rules being imposed from above rather than building blocks that help everyone.","guidance":"","image":"/images/policies.png","tags":["Policies","3rd-Party","Producers"],"stages":["Define"],"research":null,"experiences":["Onboarding","Quality","Governance"],"strategies":["apis-must-be-actively-governed"],"author":"Kin Lane"},{"name":"Technical Guidance","slug":"guidance-technical","description":"Technical guidance gives engineering teams the patterns and practices they need to build APIs that are consistent with the rest of the organization's surface area.","scope":"Business Contract","property":"none","type":"Technical guidance gives engineering teams the patterns and practices they need to build APIs that are consistent with the rest of the organization's surface area.","guidance":"","image":"/images/technical.png","tags":["Policies","3rd-Party","Producers"],"stages":["Define"],"research":null,"experiences":["Onboarding","Quality","Governance"],"strategies":["apis-must-be-actively-governed"],"author":"Kin Lane"},{"name":"Guidance","slug":"guidance","description":"Guidance is what makes governance actually work. Simple text and video resources that cover every topic teams encounter keeps everyone moving forward without constantly asking for permission or clarification.","scope":"Business Contract","property":"none","type":"Guidance is what makes governance actually work. Simple text and video resources that cover every topic teams encounter keeps everyone moving forward without constantly asking for permission or clarification.","guidance":"governance/guidance","image":"/images/guidance.png","tags":["Support","3rd-Party","Producers"],"policies":["None"],"rules":["apis-json-apis-properties-rules-info"],"stages":["Define"],"research":null,"experiences":["Onboarding","Quality","Governance"],"strategies":["apis-must-be-actively-governed"],"author":"Kin Lane"},{"name":"How Will API Be Used","slug":"how","description":"Understanding how consumers will actually use an API gets into the details of programming languages, frameworks, and integration patterns. This is where abstract capabilities become real implementations.","scope":"Business Contract","property":"none","type":"Understanding how consumers will actually use an API gets into the details of programming languages, frameworks, and integration patterns. This is where abstract capabilities become real implementations.","guidance":"use-cases/how","image":"/images/how.png","tags":["Policies","3rd-Party","Producers"],"stages":["Define","Default"],"research":null,"strategies":["apis-have-clear-business-models"],"experiences":["Alignment","Discovery"],"author":"Kin Lane"},{"name":"Human URL for APIs.json Contract","slug":"human-url","description":"The human URL is the landing page for people who want to learn about an API. It is the link you share in conversations, documentation, and catalogs so humans can find their way in.","scope":"Business Contract","property":"humanURL","type":"The human URL is the landing page for people who want to learn about an API. It is the link you share in conversations, documentation, and catalogs so humans can find their way in.","guidance":"apis/human-url","image":"/images/human-url.png","tags":["URLs"],"experiences":["Onboarding","Access"],"rules":["apis-json-apis-humanURL-info"],"stages":["Define","Default"],"research":null,"strategies":["apis-have-one-click-access"],"author":"Kin Lane"},{"name":"Usage of JSON Path Standard","slug":"json-path","description":"JSON Path gives you a standard way to point at specific properties within a schema. It is one of those utility standards that shows up everywhere once you start automating governance and validation.","scope":"Standard","property":"none","type":"JSON Path gives you a standard way to point at specific properties within a schema. It is one of those utility standards that shows up everywhere once you start automating governance and validation.","guidance":"","image":"/images/schema.png","tags":["Schema","Rules"],"stages":["Define"],"research":null,"experiences":["Consistency","Quality"],"strategies":["apis-are-aligned-with-industry-using-standards"],"author":"Kin Lane"},{"name":"API Licensing","slug":"licensing","description":"Licensing is something most API producers skip, but consumers need to understand the legal terms for using the interface, code, and data. Publishing a clear license removes ambiguity and builds trust.","scope":"Business Contract","property":"none","type":"Licensing is something most API producers skip, but consumers need to understand the legal terms for using the interface, code, and data. Publishing a clear license removes ambiguity and builds trust.","guidance":"legal/licensing","image":"/images/licenses.png","tags":["Policies","3rd-Party","Producers"],"policies":["None"],"experiences":["Onboarding","Change","Consistency","Legal"],"rules":["apis-json-apis-properties-license-info"],"stages":["Beta","Default"],"research":null,"strategies":["apis-are-legally-covered","apis-meet-regulatory-and-compliance-requirements"],"properties":["InterfaceLicense"],"author":"Kin Lane"},{"name":"Login for APIs","slug":"login","description":"Login should be as simple as possible. Every extra click or step between a consumer and accessing an API is friction that reduces adoption. Ideally this is automated, not a form.","scope":"Business Contract","property":"none","type":"Login should be as simple as possible. Every extra click or step between a consumer and accessing an API is friction that reduces adoption. Ideally this is automated, not a form.","guidance":"","image":"/images/login.png","tags":["Policies","3rd-Party","Producers"],"policies":["None"],"experiences":["Onboarding","Access"],"stages":["Define"],"research":null,"strategies":["onboarding-is-always-as-easy-as-possible"],"properties":["Login"],"author":"Kin Lane"},{"name":"Centralizing Headers Using Components","slug":"openapi-component-headers","description":"Centralizing headers in OpenAPI components keeps things like rate limit and retry-after headers consistent across operations. It is one of those governance patterns that pays off immediately.","scope":"Technical Contract","property":"none","type":"Centralizing headers in OpenAPI components keeps things like rate limit and retry-after headers consistent across operations. It is one of those governance patterns that pays off immediately.","guidance":"openapi/component-headers","image":"/images/headers.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-components-headers-rate-limit-error","openapi-components-headers-rate-limit-info","openapi-components-headers-retry-after-error","openapi-components-headers-retry-after-info"],"stages":["Develop","Default"],"research":null,"experiences":["Consistency","Quality","Reusability"],"strategies":["apis-must-reusable-whenever-possible"],"author":"Kin Lane"},{"name":"Centralizing Headers Using Components","slug":"openapi-component-headers","description":"Centralizing headers in OpenAPI components keeps things like rate limit and retry-after headers consistent across operations. It is one of those governance patterns that pays off immediately.","scope":"Technical Contract","property":"none","type":"Centralizing headers in OpenAPI components keeps things like rate limit and retry-after headers consistent across operations. It is one of those governance patterns that pays off immediately.","guidance":"openapi/component-headers","image":"/images/headers.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-components-headers-rate-limit-error","openapi-components-headers-rate-limit-info","openapi-components-headers-retry-after-error","openapi-components-headers-retry-after-info"],"stages":["Design","Default"],"research":null,"experiences":["Consistency","Quality","Reusability"],"strategies":["apis-must-reusable-whenever-possible"],"author":"Kin Lane"},{"name":"OpenAPI Components","slug":"openapi-components","description":"The components object in OpenAPI is where you centralize the reusable parts of your API definition. Parameters, schemas, examples, headers -- putting them in components reduces duplication and makes governance easier.","scope":"Technical Contract","property":"Components","type":"The components object in OpenAPI is where you centralize the reusable parts of your API definition. Parameters, schemas, examples, headers -- putting them in components reduces duplication and makes governance easier.","guidance":"openapi/components","image":"/images/components.png","tags":["Components","Reusability","Modularity"],"rules":["apis-json-common-info","openapi-components-parameters-error","openapi-components-parameters-info","openapi-components-examples-error","openapi-components-examples-info","openapi-components-schemas-error","openapi-components-schemas-info","openapi-components-headers-error","openapi-components-headers-info"],"stages":["Design","Default"],"research":null,"strategies":["apis-must-reusable-whenever-possible"],"experiences":["Consistency","Quality","Reusability"],"author":"Kin Lane"},{"name":"Providing External Document References","slug":"openapi-external-docs","description":"External documentation references in OpenAPI connect the technical contract to the broader context. Linking out to guides, tutorials, and background docs gives consumers a fuller picture.","scope":"Technical Contract","property":"none","type":"External documentation references in OpenAPI connect the technical contract to the broader context. Linking out to guides, tutorials, and background docs gives consumers a fuller picture.","guidance":"openapi/external-docs","image":"/images/documentation.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-external-docs-error","openapi-external-docs-info"],"stages":["Design","Default"],"research":null,"strategies":["apis-are-interoperable-across-systems"],"experiences":["Onboarding","Developer Experience"],"author":"Kin Lane"},{"name":"Contact Information for APIs","slug":"openapi-info-contact","description":"Contact information in your OpenAPI info section tells consumers who to reach out to. It is a small detail that makes a big difference when someone is stuck or has a question.","scope":"Technical Contract","property":"none","type":"Contact information in your OpenAPI info section tells consumers who to reach out to. It is a small detail that makes a big difference when someone is stuck or has a question.","guidance":"openapi/info-contact","image":"/images/contacts.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-info-contact-error","openapi-info-contact-info","openapi-info-contact-name-error","openapi-info-contact-name-info","openapi-info-contact-email-error","openapi-info-contact-email-info","openapi-info-contact-url-error","openapi-info-contact-url-info"],"stages":["Design","Default"],"research":null,"strategies":["api-info-and-metadata-is-complete-and-accurate"],"experiences":["Discovery","Quality","Consistency","Onboarding"],"author":"Kin Lane"},{"name":"Description of APIs","slug":"openapi-info-description","description":"The description in your OpenAPI info block is prime real estate. This is where you tell consumers what the API is about in a way that makes them want to keep reading.","scope":"Technical Contract","property":"none","type":"The description in your OpenAPI info block is prime real estate. This is where you tell consumers what the API is about in a way that makes them want to keep reading.","guidance":"openapi/info-description","image":"/images/descriptions.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-info-description-error","openapi-info-description-info","openapi-info-description-length-error"],"stages":["Design","Default"],"research":null,"strategies":["api-info-and-metadata-is-complete-and-accurate"],"experiences":["Discovery","Quality","Consistency","Onboarding"],"author":"Kin Lane"},{"name":"License for APIs","slug":"openapi-info-license","description":"Including a license in your OpenAPI info section makes the legal terms explicit. I see way too many APIs where consumers have no idea what they are legally allowed to do.","scope":"Technical Contract","property":"none","type":"Including a license in your OpenAPI info section makes the legal terms explicit. I see way too many APIs where consumers have no idea what they are legally allowed to do.","guidance":"openapi/info-license","image":"/images/licenses.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-info-license-error","openapi-info-license-identifier-cc-by-nc-sa-error","openapi-info-license-identifier-cc-by-nc-sa-info","openapi-info-license-identifier-error","openapi-info-license-identifier-info","openapi-info-license-info","openapi-info-license-name-error","openapi-info-license-name-info","openapi-info-license-url-error","openapi-info-license-url-info"],"stages":["Beta","Default"],"research":null,"strategies":["api-info-and-metadata-is-complete-and-accurate"],"experiences":["Discovery","Quality","Consistency","Onboarding"],"author":"Kin Lane"},{"name":"Terms of Service for APIs","slug":"openapi-info-terms-of-service","description":"Terms of service linked from your OpenAPI info give consumers the legal context they need. Making this part of the technical contract means it travels everywhere the spec goes.","scope":"Technical Contract","property":"none","type":"Terms of service linked from your OpenAPI info give consumers the legal context they need. Making this part of the technical contract means it travels everywhere the spec goes.","guidance":"openapi/info-terms-of-service","image":"/images/terms-of-service.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-info-terms-of-service-error","openapi-info-terms-of-service-info"],"stages":["Beta","Default"],"research":null,"strategies":["api-info-and-metadata-is-complete-and-accurate"],"experiences":["Discovery","Quality","Consistency","Onboarding"],"author":"Kin Lane"},{"name":"Title of APIs","slug":"openapi-info-title","description":"The title in your OpenAPI is the name that shows up everywhere -- in docs, catalogs, and code generation. Getting the casing, length, and clarity right here sets the tone for everything.","scope":"Technical Contract","property":"none","type":"The title in your OpenAPI is the name that shows up everywhere -- in docs, catalogs, and code generation. Getting the casing, length, and clarity right here sets the tone for everything.","guidance":"openapi/info-title","image":"/images/names.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-info-title-error","openapi-info-title-info","openapi-info-title-length-error","openapi-info-title-upper-case-error","openapi-info-title-upper-case-info"],"stages":["Design","Default"],"research":null,"strategies":["api-info-and-metadata-is-complete-and-accurate"],"experiences":["Discovery","Quality","Consistency","Onboarding"],"author":"Kin Lane"},{"name":"Version of APIs","slug":"openapi-info-version","description":"Version information in your OpenAPI tells consumers which release they are looking at. Whether you use semantic versioning or date-based, having it in the spec is how you communicate where things stand.","scope":"Technical Contract","property":"none","type":"Version information in your OpenAPI tells consumers which release they are looking at. Whether you use semantic versioning or date-based, having it in the spec is how you communicate where things stand.","guidance":"openapi/info-version","image":"/images/versions.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-info-version-error","openapi-info-version-info","openapi-version-date-info","openapi-version-semantic-info"],"stages":["Design","Default"],"research":null,"strategies":["api-info-and-metadata-is-complete-and-accurate","api-versioning-follows-a-defined-standard"],"experiences":["Discovery","Quality","Consistency","Onboarding"],"author":"Kin Lane"},{"name":"Description of API Operations","slug":"openapi-operation-description","description":"Operation descriptions are where you explain what each endpoint actually does. A missing or weak description means consumers have to guess, and guessing leads to bad integrations.","scope":"Technical Contract","property":"none","type":"Operation descriptions are where you explain what each endpoint actually does. A missing or weak description means consumers have to guess, and guessing leads to bad integrations.","guidance":"openapi/operation-description","image":"/images/descriptions.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-operations-description-error","openapi-operations-description-info","openapi-operations-description-length-error"],"stages":["Design","Default"],"research":null,"strategies":["operations-must-be-useful-and-consistent"],"experiences":["Onboarding","Quality","Developer Experience"],"author":"Kin Lane"},{"name":"Unique Identrifiers for API Operations","slug":"openapi-operation-identifiers","description":"Operation IDs give each endpoint a unique, machine-readable name. SDKs, code generators, and documentation tools all depend on these being consistent and meaningful.","scope":"Technical Contract","property":"none","type":"Operation IDs give each endpoint a unique, machine-readable name. SDKs, code generators, and documentation tools all depend on these being consistent and meaningful.","guidance":"openapi/operation-identifiers","image":"/images/unique-identifiers.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-operations-operation-ids-error","openapi-operations-operation-ids-info","openapi-operations-operation-ids-camel-case-error","openapi-operations-operation-ids-camel-case-info"],"stages":["Develop","Default"],"research":null,"strategies":["operations-must-be-useful-and-consistent"],"experiences":["Consistency","Quality","Developer Experience"],"author":"Kin Lane"},{"name":"Parameter Descriptions","slug":"openapi-operation-parameter-descriptions","description":"Parameter descriptions tell consumers what each input actually means and how to use it. Without good descriptions, parameters are just names that people have to reverse-engineer.","scope":"Technical Contract","property":"none","type":"Parameter descriptions tell consumers what each input actually means and how to use it. Without good descriptions, parameters are just names that people have to reverse-engineer.","guidance":"openapi/operation-parameter-description","image":"/images/parameter-descriptions.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-components-parameters-description-error","openapi-components-parameters-description-info","openapi-components-parameters-description-length-error"],"stages":["Design","Default"],"research":null,"strategies":["api-parameters-are-well-defined-and-consistent","operations-must-be-useful-and-consistent"],"experiences":["Consistency","Quality","Developer Experience"],"author":"Kin Lane"},{"name":"Parameter Enumerators","slug":"openapi-operation-parameter-enum","description":"Enumerators on parameters tell consumers exactly what values are valid. This is way better than letting people guess and get back cryptic error messages.","scope":"Technical Contract","property":"none","type":"Enumerators on parameters tell consumers exactly what values are valid. This is way better than letting people guess and get back cryptic error messages.","guidance":"openapi/operation-parameter-enum","image":"/images/enumerators.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-components-parameters-enum-casing-error","openapi-components-parameters-enum-casing-info","openapi-components-parameters-enum-info"],"stages":["Design","Default"],"research":null,"strategies":["api-parameters-are-well-defined-and-consistent","operations-must-be-useful-and-consistent"],"experiences":["Consistency","Quality","Developer Experience"],"author":"Kin Lane"},{"name":"Parameter In Query or Path","slug":"openapi-operation-parameter-in","description":"Specifying whether a parameter goes in the query string, path, or header seems basic, but getting it wrong causes real confusion. This needs to be explicit and correct.","scope":"Technical Contract","property":"none","type":"Specifying whether a parameter goes in the query string, path, or header seems basic, but getting it wrong causes real confusion. This needs to be explicit and correct.","guidance":"openapi/operation-parameter-in","image":"/images/parameters.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-components-parameters-in-error","openapi-components-parameters-in-info"],"stages":["Design","Default"],"research":null,"strategies":["api-parameters-are-well-defined-and-consistent","operations-must-be-useful-and-consistent"],"experiences":["Consistency","Quality","Developer Experience"],"author":"Kin Lane"},{"name":"Parameter Names","slug":"openapi-operation-parameter-names","description":"Parameter names are part of your API's surface area that consumers interact with directly. Consistent naming, proper casing, and reasonable length all matter here.","scope":"Technical Contract","property":"none","type":"Parameter names are part of your API's surface area that consumers interact with directly. Consistent naming, proper casing, and reasonable length all matter here.","guidance":"openapi/operation-parameter-names","image":"/images/parameter-names.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-components-parameters-name-error","openapi-components-parameters-name-info","openapi-components-parameters-name-length-error","openapi-components-parameters-casing-camel-warn","openapi-components-parameters-casing-camel-info"],"stages":["Design","Default"],"research":null,"strategies":["api-parameters-are-well-defined-and-consistent","operations-must-be-useful-and-consistent"],"experiences":["Consistency","Quality","Developer Experience"],"author":"Kin Lane"},{"name":"Parameter Schema","slug":"openapi-operation-parameter-schema","description":"Schema definitions on parameters give you type safety and validation. Referencing shared schemas keeps things consistent and makes governance rules easier to apply.","scope":"Technical Contract","property":"none","type":"Schema definitions on parameters give you type safety and validation. Referencing shared schemas keeps things consistent and makes governance rules easier to apply.","guidance":"openapi/operation-parameter-schema","image":"/images/schema.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-components-parameters-schema-error","openapi-components-parameters-schema-info","openapi-components-parameters-schema-ref-error","openapi-components-parameters-schema-ref-info"],"stages":["Design","Default"],"research":null,"strategies":["api-parameters-are-well-defined-and-consistent","operations-must-be-useful-and-consistent"],"experiences":["Consistency","Quality","Developer Experience"],"author":"Kin Lane"},{"name":"Parameter Types","slug":"openapi-operation-parameter-types","description":"Getting parameter types right -- integers, strings, arrays, numbers -- with proper formats and constraints prevents a whole category of integration bugs before they happen.","scope":"Technical Contract","property":"none","type":"Getting parameter types right -- integers, strings, arrays, numbers -- with proper formats and constraints prevents a whole category of integration bugs before they happen.","guidance":"openapi/operation-parameter-types","image":"/images/types.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-schema-properties-allowed-integer-format-error","openapi-schema-properties-allowed-number-format-error","openapi-schema-properties-array-items-error","openapi-schema-properties-array-items-info","openapi-schema-properties-array-maxitems-error","openapi-schema-properties-array-maxitems-info","openapi-schema-properties-array-minitems-error","openapi-schema-properties-array-minitems-info","openapi-schema-properties-define-number-maximum-error","openapi-schema-properties-define-number-minimum-error","openapi-schema-properties-string-maxlength-error","openapi-schema-properties-string-maxlength-info","openapi-schema-properties-string-minlength-error","openapi-schema-properties-string-minlength-info"],"stages":["Design","Default"],"research":null,"strategies":["api-parameters-are-well-defined-and-consistent","operations-must-be-useful-and-consistent"],"experiences":["Consistency","Quality","Developer Experience"],"author":"Kin Lane"},{"name":"Parameters","slug":"openapi-operation-parameters","description":"Parameters are the inputs consumers use to customize their API calls. Componentizing them keeps things consistent across operations and makes the whole surface area easier to govern.","scope":"Technical Contract","property":"none","type":"Parameters are the inputs consumers use to customize their API calls. Componentizing them keeps things consistent across operations and makes the whole surface area easier to govern.","guidance":"openapi/operation-parameters","image":"/images/parameters.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-parameters-componentized-error","openapi-parameters-componentized-info"],"stages":["Design","Default"],"research":null,"strategies":["api-parameters-are-well-defined-and-consistent","operations-must-be-useful-and-consistent"],"experiences":["Consistency","Quality","Developer Experience"],"author":"Kin Lane"},{"name":"Request Bodies Examples","slug":"openapi-operation-request-bodies-examples","description":"Request body examples show consumers exactly what to send. Without realistic examples, developers are stuck guessing at payload structure and wasting time on trial and error.","scope":"Technical Contract","property":"none","type":"Request body examples show consumers exactly what to send. Without realistic examples, developers are stuck guessing at payload structure and wasting time on trial and error.","guidance":"openapi/operation-request-bodies-examples","image":"/images/examples.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-request-body-have-examples-error","openapi-request-body-have-examples-info","openapi-request-body-have-examples-ref-error","openapi-request-body-have-examples-ref-info"],"stages":["Design","Default"],"research":null,"strategies":["operations-must-be-useful-and-consistent"],"experiences":["Consistency","Quality","Developer Experience"],"author":"Kin Lane"},{"name":"Request Bodies Media Types","slug":"openapi-operation-request-bodies-media-types","description":"Media types on request bodies tell consumers what content types the API accepts. Getting this right avoids the confusion that comes when JSON and form data expectations do not match.","scope":"Technical Contract","property":"none","type":"Media types on request bodies tell consumers what content types the API accepts. Getting this right avoids the confusion that comes when JSON and form data expectations do not match.","guidance":"openapi/operation-request-bodies-media-type","image":"/images/media-types.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-request-body-have-application-json-info","openapi-request-body-have-application-x-www-form-url-encoded-info"],"stages":["Design","Default"],"research":null,"strategies":["operations-must-be-useful-and-consistent"],"experiences":["Consistency","Quality","Interoperability"],"author":"Kin Lane"},{"name":"Request Bodies Schema","slug":"openapi-operation-request-bodies-schema","description":"Schema definitions on request bodies are how you validate what consumers send. Referencing shared schemas and requiring bodies on POST and PUT keeps things predictable.","scope":"Technical Contract","property":"none","type":"Schema definitions on request bodies are how you validate what consumers send. Referencing shared schemas and requiring bodies on POST and PUT keeps things predictable.","guidance":"openapi/operation-request-bodies-schema","image":"/images/schema.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-request-body-have-schema-error","openapi-request-body-have-schema-info","openapi-request-body-have-schema-ref-error","openapi-request-body-have-schema-ref-info","openapi-request-body-on-post-error","openapi-request-body-on-post-info","openapi-request-body-on-put-error-info","openapi-request-body-on-put-info","openapi-response-put-204-no-body-error","openapi-response-delete-204-no-body-error"],"stages":["Design","Default"],"research":null,"strategies":["operations-must-be-useful-and-consistent"],"experiences":["Consistency","Quality","Developer Experience"],"author":"Kin Lane"},{"name":"Request Bodies","slug":"openapi-operation-request-bodies","description":"Request bodies are one of the most complex parts of an API to get right. Descriptions, required fields, content types, and validation all need to be present and consistent.","scope":"Technical Contract","property":"none","type":"Request bodies are one of the most complex parts of an API to get right. Descriptions, required fields, content types, and validation all need to be present and consistent.","guidance":"openapi/operation-request-bodies","image":"/images/request-bodies.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-no-request-body-on-delete-error","openapi-no-request-body-on-delete-info","openapi-no-request-body-on-get-error","openapi-no-request-body-on-get-info","openapi-request-bodies-description-error","openapi-request-bodies-description-info","openapi-request-bodies-required-property-error","openapi-request-bodies-required-property-info","openapi-request-body-content-on-post-error","openapi-request-body-content-on-post-info","openapi-request-body-content-on-put-error","openapi-request-body-content-on-put-info"],"stages":["Design","Default"],"research":null,"strategies":["operations-must-be-useful-and-consistent"],"experiences":["Consistency","Quality","Developer Experience"],"author":"Kin Lane"},{"name":"Response 2xx","slug":"openapi-operation-response-2xx","description":"Success responses are what consumers are building their applications around. Having complete schema, examples, and descriptions for every 2xx response is not optional -- it is the baseline.","scope":"Technical Contract","property":"none","type":"Success responses are what consumers are building their applications around. Having complete schema, examples, and descriptions for every 2xx response is not optional -- it is the baseline.","guidance":"openapi/operation-response-2xx","image":"/images/check.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-response-get-200-status-code-error","openapi-response-get-200-status-code-info","openapi-response-get-200-description-error","openapi-response-get-200-description-info","openapi-response-get-200-content-error","openapi-response-get-200-content-info","openapi-response-get-200-media-type-error","openapi-response-get-200-media-type-info","openapi-response-get-200-media-type-schema-error","openapi-response-get-200-media-type-schema-info","openapi-response-get-200-media-type-schema-ref-error","openapi-response-get-200-media-type-schema-ref-info","openapi-response-get-200-media-type-examples-error","openapi-response-get-200-media-type-examples-info","openapi-response-get-200-media-type-examples-ref-error","openapi-response-get-200-media-type-examples-ref-info","openapi-response-post-201-media-type-schema-error","openapi-response-post-201-media-type-schema-info","openapi-response-post-201-schema-ref-error","openapi-response-post-201-schema-ref-info","openapi-response-post-201-status-code-error","openapi-response-post-201-status-code-info","openapi-response-post-201-description-error","openapi-response-post-201-description-info","openapi-response-post-201-content-error","openapi-response-post-201-content-info","openapi-response-post-201-media-type-error","openapi-response-post-201-media-type-info","openapi-response-post-201-media-type-examples-error","openapi-response-post-201-media-type-examples-info","openapi-response-post-201-examples-ref-error","openapi-response-post-201-examples-ref-info","openapi-response-put-204-status-code-error","openapi-response-put-204-status-code-info","openapi-response-delete-204-status-code-error","openapi-response-delete-204-status-code-info"],"stages":["Design","Default"],"research":null,"strategies":["api-responses-must-be-meaningful-and-consistent"],"experiences":["Consistency","Quality","Reliability","Developer Experience"],"author":"Kin Lane"},{"name":"Response 4xx","slug":"openapi-operation-response-4xx","description":"Client error responses are where developer experience lives or dies. Consistent 400, 401, 403, 404, and 429 responses with shared schema references make error handling predictable.","scope":"Technical Contract","property":"none","type":"Client error responses are where developer experience lives or dies. Consistent 400, 401, 403, 404, and 429 responses with shared schema references make error handling predictable.","guidance":"openapi/operation-response-4xx","image":"/images/not-found.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-response-get-400-status-code-error","openapi-response-get-400-status-code-info","openapi-response-get-401-status-code-info","openapi-response-get-401-status-code-error","openapi-response-get-403-status-code-info","openapi-response-get-403-status-code-error","openapi-response-get-404-status-code-error","openapi-response-get-404-status-code-info","openapi-response-get-429-status-code-info","openapi-response-get-429-status-code-error","openapi-response-get-400-schema-ref-error","openapi-response-get-400-schema-ref-info","openapi-response-get-401-schema-ref-error","openapi-response-get-401-schema-ref-info","openapi-response-get-403-schema-ref-error","openapi-response-get-403-schema-ref-info","openapi-response-get-404-schema-ref-error","openapi-response-get-404-schema-ref-info","openapi-response-get-429-schema-ref-error","openapi-response-get-429-schema-ref-info","openapi-response-post-400-status-code-info","openapi-response-post-400-status-code-error","openapi-response-post-401-status-code-info","openapi-response-post-401-status-code-error","openapi-response-post-403-status-code-info","openapi-response-post-403-status-code-error","openapi-response-post-404-status-code-info","openapi-response-post-404-status-code-error","openapi-response-post-429-status-code-error","openapi-response-post-429-status-code-info","openapi-response-post-400-schema-ref-error","openapi-response-post-400-schema-ref-info","openapi-response-post-401-schema-ref-error","openapi-response-post-401-schema-ref-info","openapi-response-post-403-schema-ref-error","openapi-response-post-403-schema-ref-info","openapi-response-post-404-schema-ref-error","openapi-response-post-404-schema-ref-info","openapi-response-post-429-schema-ref-error","openapi-response-post-429-schema-ref-info","openapi-response-put-400-status-code-error","openapi-response-put-400-status-code-info","openapi-response-put-401-status-code-error","openapi-response-put-401-status-code-info","openapi-response-put-403-status-code-error","openapi-response-put-403-status-code-info","openapi-response-put-404-status-code-error","openapi-response-put-404-status-code-info","openapi-response-put-429-status-code-error","openapi-response-put-429-status-code-info","openapi-response-put-400-schema-ref-error","openapi-response-put-400-schema-ref-info","openapi-response-put-401-schema-ref-error","openapi-response-put-401-schema-ref-info","openapi-response-put-403-schema-ref-error","openapi-response-put-403-schema-ref-info","openapi-response-put-404-schema-ref-error","openapi-response-put-404-schema-ref-info","openapi-response-put-429-schema-ref-error","openapi-response-put-429-schema-ref-info","openapi-response-delete-400-status-code-error","openapi-response-delete-400-status-code-info","openapi-response-delete-401-status-code-error","openapi-response-delete-401-status-code-info","openapi-response-delete-403-status-code-error","openapi-response-delete-403-status-code-info","openapi-response-delete-404-status-code-error","openapi-response-delete-404-status-code-info","openapi-response-delete-429-status-code-error","openapi-response-delete-429-status-code-info","openapi-response-delete-400-schema-ref-error","openapi-response-delete-400-schema-ref-info","openapi-response-delete-401-schema-ref-error","openapi-response-delete-401-schema-ref-info","openapi-response-delete-403-schema-ref-error","openapi-response-delete-403-schema-ref-info","openapi-response-delete-404-schema-ref-error","openapi-response-delete-404-schema-ref-info","openapi-response-delete-429-schema-ref-error","openapi-response-delete-429-schema-ref-info"],"stages":["Design","Default"],"research":null,"strategies":["api-errors-are-standardized-and-informative","api-responses-must-be-meaningful-and-consistent"],"experiences":["Consistency","Quality","Reliability","Developer Experience"],"author":"Kin Lane"},{"name":"Response 5xx","slug":"openapi-operation-response-5xx","description":"Server error responses need the same consistency as everything else. Having standardized 500 responses with proper schema references lets consumers build reliable error handling.","scope":"Technical Contract","property":"none","type":"Server error responses need the same consistency as everything else. Having standardized 500 responses with proper schema references lets consumers build reliable error handling.","guidance":"openapi/operation-response-5xx","image":"/images/error.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-response-get-500-status-code-error","openapi-response-get-500-status-code-info","openapi-response-get-500-schema-ref-error","openapi-response-get-500-schema-ref-info","openapi-response-post-500-status-code-error","openapi-response-post-500-status-code-info","openapi-response-post-500-schema-ref-error","openapi-response-post-500-schema-ref-info","openapi-response-put-500-status-code-error","openapi-response-put-500-status-code-info","openapi-response-put-500-schema-ref-error","openapi-response-put-500-schema-ref-info","openapi-response-delete-500-status-code-error","openapi-response-delete-500-status-code-info","openapi-response-delete-500-schema-ref-error","openapi-response-delete-500-schema-ref-info"],"stages":["Design","Default"],"research":null,"strategies":["api-errors-are-standardized-and-informative","api-responses-must-be-meaningful-and-consistent"],"experiences":["Consistency","Quality","Reliability","Developer Experience"],"author":"Kin Lane"},{"name":"Operation Security","slug":"openapi-operation-security","description":"Security definitions on operations make access requirements explicit. Every operation should clearly state what authentication and authorization is required to call it.","scope":"Technical Contract","property":"none","type":"Security definitions on operations make access requirements explicit. Every operation should clearly state what authentication and authorization is required to call it.","guidance":"openapi/operation-security","image":"/images/security.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-operation-security-definitions-error","openapi-operation-security-definitions-info"],"stages":["Design","Default"],"research":null,"strategies":["api-authentication-is-standardized","api-authorization-is-properly-defined-and-enforced","operations-must-be-useful-and-consistent"],"experiences":["Security","Access","Trust"],"author":"Kin Lane"},{"name":"Operation Summary","slug":"openapi-operation-summary","description":"Operation summaries are the short labels consumers scan when browsing documentation. They need to be concise, descriptive, and follow consistent patterns across all operations.","scope":"Technical Contract","property":"none","type":"Operation summaries are the short labels consumers scan when browsing documentation. They need to be concise, descriptive, and follow consistent patterns across all operations.","guidance":"openapi/operation-summary","image":"/images/summaries.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-operations-summary-error","openapi-operations-summary-info","openapi-operations-summary-length-error","openapi-operations-summary-period-none-error","openapi-operations-summary-period-none-info"],"stages":["Design","Default"],"research":null,"strategies":["operations-must-be-useful-and-consistent"],"experiences":["Onboarding","Quality","Developer Experience"],"author":"Kin Lane"},{"name":"Operation Tags","slug":"openapi-operation-tags","description":"Tags on operations organize endpoints into logical groups. They drive how documentation is structured and how consumers discover related functionality within an API.","scope":"Technical Contract","property":"none","type":"Tags on operations organize endpoints into logical groups. They drive how documentation is structured and how consumers discover related functionality within an API.","guidance":"openapi/operation-tags","image":"/images/tags.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-operations-tags-error","openapi-operations-tags-info","openapi-operations-tags-one-error","openapi-operations-tags-upper-case-error","openapi-operations-tags-upper-case-info"],"stages":["Design","Default"],"research":null,"strategies":["operations-must-be-useful-and-consistent"],"experiences":["Discovery","Consistency"],"author":"Kin Lane"},{"name":"Path Names","slug":"openapi-path-names","description":"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.","scope":"Technical Contract","property":"none","type":"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.","guidance":"openapi/paths","image":"/images/names.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-no-api-in-path-error","openapi-no-api-in-path-info","openapi-no-path-trailing-slash-error","openapi-no-path-trailing-slash-info","openapi-version-in-path-error","openapi-version-in-path-info"],"stages":["Design","Default"],"research":null,"strategies":["api-paths-must-conform-to-the-organization","apis-follow-consistent-design-patterns"],"experiences":["Consistency","Simplicity","Developer Experience"],"author":"Kin Lane"},{"name":"Schema Descriptions","slug":"openapi-schema-descriptions","description":"Schema descriptions tell consumers what each data structure represents. Without them, people are left reading property names and trying to infer the meaning of the whole object.","scope":"Technical Contract","property":"none","type":"Schema descriptions tell consumers what each data structure represents. Without them, people are left reading property names and trying to infer the meaning of the whole object.","guidance":"openapi/schema-description","image":"/images/descriptions.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-schema-description-error","openapi-schema-description-info","openapi-schema-description-length-error"],"stages":["Design","Default"],"research":null,"strategies":["data-should-be-well-defined-and-validated"],"experiences":["Consistency","Quality","Interoperability"],"author":"Kin Lane"},{"name":"Schema Names","slug":"openapi-schema-names","description":"Schema names should follow consistent casing conventions and be descriptive enough that you know what they represent without reading the properties. Pascal case is what I see working best.","scope":"Technical Contract","property":"none","type":"Schema names should follow consistent casing conventions and be descriptive enough that you know what they represent without reading the properties. Pascal case is what I see working best.","guidance":"openapi/schema-names","image":"/images/names.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-schema-names-pascal-case-error","openapi-schema-names-pascal-case-info","openapi-schema-names-length-error"],"stages":["Design","Default"],"research":null,"strategies":["data-should-be-well-defined-and-validated"],"experiences":["Consistency","Quality","Interoperability"],"author":"Kin Lane"},{"name":"Schema Properties","slug":"openapi-schema-properties","description":"Schema properties are the individual data points that flow through your API. Having them well-defined with types, descriptions, and constraints is how you prevent data quality issues.","scope":"Technical Contract","property":"none","type":"Schema properties are the individual data points that flow through your API. Having them well-defined with types, descriptions, and constraints is how you prevent data quality issues.","guidance":"openapi/schema-properties","image":"/images/properties.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-schema-properties-error","openapi-schema-properties-info"],"stages":["Design","Default"],"research":null,"strategies":["data-should-be-well-defined-and-validated"],"experiences":["Consistency","Quality","Interoperability"],"author":"Kin Lane"},{"name":"Schema Property Descriptions","slug":"openapi-schema-property-descriptions","description":"Property descriptions explain what each field means in context. This is especially important for fields where the name alone does not tell the full story.","scope":"Technical Contract","property":"none","type":"Property descriptions explain what each field means in context. This is especially important for fields where the name alone does not tell the full story.","guidance":"openapi/schema-property-descriptions","image":"/images/descriptions.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-schema-properties-descriptions-error","openapi-schema-properties-descriptions-info","openapi-schema-properties-descriptions-length-error"],"stages":["Design","Default"],"research":null,"strategies":["data-should-be-well-defined-and-validated"],"experiences":["Consistency","Quality","Interoperability"],"author":"Kin Lane"},{"name":"Schema Property Names","slug":"openapi-schema-property-names","description":"Property names are part of the contract consumers code against. Consistent casing, reasonable length, and meaningful names make the difference between an API that is intuitive and one that is frustrating.","scope":"Technical Contract","property":"none","type":"Property names are part of the contract consumers code against. Consistent casing, reasonable length, and meaningful names make the difference between an API that is intuitive and one that is frustrating.","guidance":"openapi/schema-property-names","image":"/images/names.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-schema-properties-names-camel-case-error","openapi-schema-properties-names-camel-case-info","openapi-schema-properties-names-length-error"],"stages":["Design","Default"],"research":null,"strategies":["data-should-be-well-defined-and-validated"],"experiences":["Consistency","Quality","Interoperability"],"author":"Kin Lane"},{"name":"Schema Property Shapes","slug":"openapi-schema-property-shapes","description":"Property shapes -- min and max lengths, array bounds, number ranges -- define the constraints on your data. These constraints are what prevent garbage data from flowing through your APIs.","scope":"Technical Contract","property":"none","type":"Property shapes -- min and max lengths, array bounds, number ranges -- define the constraints on your data. These constraints are what prevent garbage data from flowing through your APIs.","guidance":"openapi/schema-property-shapes","image":"/images/shapes.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-schema-properties-string-maxlength-error","openapi-schema-properties-string-maxlength-info","openapi-schema-properties-string-minlength-error","openapi-schema-properties-string-minlength-info","openapi-schema-properties-array-items-error","openapi-schema-properties-array-items-info","openapi-schema-properties-array-maxitems-error","openapi-schema-properties-array-maxitems-info","openapi-schema-properties-array-minitems-error","openapi-schema-properties-array-minitems-info","openapi-schema-properties-define-number-maximum-error","openapi-schema-properties-define-number-minimum-error"],"stages":["Design","Default"],"research":null,"strategies":["data-should-be-well-defined-and-validated"],"experiences":["Consistency","Quality","Interoperability"],"author":"Kin Lane"},{"name":"Schema Property Type","slug":"openapi-schema-property-types","description":"Property types define what kind of data each field holds. Getting the types, formats, and array item definitions right is fundamental to an API that works predictably.","scope":"Technical Contract","property":"none","type":"Property types define what kind of data each field holds. Getting the types, formats, and array item definitions right is fundamental to an API that works predictably.","guidance":"openapi/schema-property-types","image":"/images/types.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-schema-properties-array-items-error","openapi-schema-properties-array-items-info","openapi-schema-properties-allowed-integer-format-error","openapi-schema-properties-allowed-number-format-error"],"stages":["Design","Default"],"research":null,"strategies":["data-should-be-well-defined-and-validated"],"experiences":["Consistency","Quality","Interoperability"],"author":"Kin Lane"},{"name":"Schema Type","slug":"openapi-schema-type","description":"Every schema needs a type. Without it, validation tools and code generators can not do their job, and consumers have no way to know what shape of data to expect.","scope":"Technical Contract","property":"none","type":"Every schema needs a type. Without it, validation tools and code generators can not do their job, and consumers have no way to know what shape of data to expect.","guidance":"openapi/schema-type","image":"/images/types.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-schema-type-error","openapi-schema-type-info"],"stages":["Design","Default"],"research":null,"strategies":["data-should-be-well-defined-and-validated"],"experiences":["Consistency","Quality","Interoperability"],"author":"Kin Lane"},{"name":"OpenAPI Security","slug":"openapi-security","description":"Security schemes in OpenAPI define how authentication works at the spec level. This is where API keys, OAuth, and other security patterns become part of the machine-readable contract.","scope":"Technical Contract","property":"none","type":"Security schemes in OpenAPI define how authentication works at the spec level. This is where API keys, OAuth, and other security patterns become part of the machine-readable contract.","guidance":"openapi/security","image":"/images/security.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-security-schemes-error","openapi-security-schemes-info"],"stages":["Design","Default"],"research":null,"strategies":["api-authentication-is-standardized","api-authorization-is-properly-defined-and-enforced","operations-must-always-be-secure"],"experiences":["Security","Access","Trust"],"author":"Kin Lane"},{"name":"OpenAPI Tags","slug":"openapi-tags","description":"Tags at the OpenAPI level organize your API into logical groups. They need names, descriptions, and consistent casing to actually serve their purpose in documentation and discovery.","scope":"Technical Contract","property":"none","type":"Tags at the OpenAPI level organize your API into logical groups. They need names, descriptions, and consistent casing to actually serve their purpose in documentation and discovery.","guidance":"openapi/tags","image":"/images/tags.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-tags-description-error","openapi-tags-description-info","openapi-tags-name-error","openapi-tags-name-info","openapi-tags-object-error","openapi-tags-object-info","openapi-tags-one-error","openapi-tags-upper-case-error"],"stages":["Design","Default"],"research":null,"strategies":["api-info-and-metadata-is-complete-and-accurate"],"experiences":["Discovery","Consistency"],"author":"Kin Lane"},{"name":"OpenAPI Version","slug":"openapi-version","description":"Using the latest version of OpenAPI keeps your specs aligned with what tooling supports. Falling behind on spec versions means missing out on features and governance capabilities.","scope":"Technical Contract","property":"none","type":"Using the latest version of OpenAPI keeps your specs aligned with what tooling supports. Falling behind on spec versions means missing out on features and governance capabilities.","guidance":"openapi/versions","image":"/images/versions.png","tags":["Policies","3rd-Party","Producers"],"stages":["Design","Default"],"research":null,"strategies":["api-info-and-metadata-is-complete-and-accurate"],"experiences":["Consistency","Change","Stability"],"author":"Kin Lane"},{"name":"OpenAPI","slug":"openapi","description":"OpenAPI is the technical contract that describes the surface area of each API in a machine-readable way. Documentation, SDKs, testing, and governance all flow from this single artifact.","scope":"Technical Contract","property":"none","type":"OpenAPI is the technical contract that describes the surface area of each API in a machine-readable way. Documentation, SDKs, testing, and governance all flow from this single artifact.","guidance":"contracts/openapi","image":"/images/openapi.png","tags":["Policies","3rd-Party","Producers"],"experiences":["Access","Automation","Change","Consistency","Discovery","Onboarding","Self-Service"],"rules":["apis-json-apis-properties-openapi-info"],"stages":["Design","Default"],"research":null,"strategies":["apis-are-defined-by-technical-contracts"],"properties":["OpenAPI"],"author":"Kin Lane"},{"name":"Latency","slug":"performance-latency","description":"Latency numbers tell consumers what to expect from an API in real-world conditions. Publishing this information sets honest expectations and helps consumers architect their applications accordingly.","scope":"Business Contract","property":"none","type":"Latency numbers tell consumers what to expect from an API in real-world conditions. Publishing this information sets honest expectations and helps consumers architect their applications accordingly.","guidance":"","image":"/images/latency.png","tags":["Testing"],"stages":["Beta"],"research":null,"strategies":["apis-are-observable-and-monitored"],"experiences":["Performance","Reliability","Observability"],"properties":["Performance"],"author":"Kin Lane"},{"name":"Response Time","slug":"performance-response-time","description":"Response time is one of the first things consumers want to know about an API. Being transparent about typical response times builds trust and helps people plan their integrations.","scope":"Business Contract","property":"none","type":"Response time is one of the first things consumers want to know about an API. Being transparent about typical response times builds trust and helps people plan their integrations.","guidance":"","image":"/images/response-time.png","tags":["Testing"],"stages":["Beta"],"research":null,"strategies":["apis-are-observable-and-monitored"],"experiences":["Performance","Reliability","Observability"],"properties":["Performance"],"author":"Kin Lane"},{"name":"Performance","slug":"performance","description":"Performance data complements status and uptime by drilling into the details that matter -- speed, latency, and throughput. Publishing this openly is how you show consumers you take reliability seriously.","scope":"Business Contract","property":"none","type":"Performance data complements status and uptime by drilling into the details that matter -- speed, latency, and throughput. Publishing this openly is how you show consumers you take reliability seriously.","guidance":"monitoring/performance","image":"/images/performance.png","tags":["Testing"],"experiences":["Automation","Communication","Quality","Reliability","Performance","Observability"],"rules":["apis-json-apis-properties-performance-info"],"stages":["Beta"],"research":null,"strategies":["apis-are-always-high-quality-and-reliable","apis-are-observable-and-monitored","apis-earn-and-maintain-consumer-trust"],"properties":["Performance"],"author":"Kin Lane"},{"name":"Elements","slug":"plan-elements","description":"Breaking down what features and capabilities are included in each plan helps consumers understand the scope of what they are getting. Transparency here prevents surprises later.","scope":"Business Contract","property":"none","type":"Breaking down what features and capabilities are included in each plan helps consumers understand the scope of what they are getting. Transparency here prevents surprises later.","guidance":"","image":"/images/elements.png","tags":["Policies","3rd-Party","Producers"],"stages":["Beta"],"research":null,"strategies":["apis-have-clear-business-models","apis-have-clear-service-level-commitments"],"experiences":["Money","Onboarding","Access"],"properties":["Plans"],"author":"Kin Lane"},{"name":"Metrics","slug":"plan-metrics","description":"Metrics within a plan explain how usage is measured. Consumers need to understand what counts against their quota so they can build their applications accordingly.","scope":"Business Contract","property":"none","type":"Metrics within a plan explain how usage is measured. Consumers need to understand what counts against their quota so they can build their applications accordingly.","guidance":"","image":"/images/metrics.png","tags":["Policies","3rd-Party","Producers"],"stages":["Beta"],"research":null,"strategies":["apis-have-clear-business-models","apis-have-clear-service-level-commitments"],"experiences":["Money","Onboarding","Access"],"properties":["Plans"],"author":"Kin Lane"},{"name":"Rate Limits","slug":"plan-rate-limits","description":"Rate limits are the guardrails of API consumption. Being explicit about what limits apply at each plan level lets consumers build applications that work within the boundaries.","scope":"Business Contract","property":"none","type":"Rate limits are the guardrails of API consumption. Being explicit about what limits apply at each plan level lets consumers build applications that work within the boundaries.","guidance":"","image":"/images/rate-limits.png","tags":["Policies","3rd-Party","Producers"],"stages":["Beta"],"research":null,"strategies":["apis-are-protected-from-abuse-and-misuse","apis-have-clear-business-models","apis-have-clear-service-level-commitments","apis-scale-efficiently-under-load"],"experiences":["Money","Onboarding","Access"],"properties":["Plans","RateLimits"],"author":"Kin Lane"},{"name":"Regions","slug":"plan-regions","description":"Regional availability matters for performance and compliance. When APIs are available in specific geographic regions, consumers need to know so they can route traffic appropriately.","scope":"Business Contract","property":"none","type":"Regional availability matters for performance and compliance. When APIs are available in specific geographic regions, consumers need to know so they can route traffic appropriately.","guidance":"","image":"/images/regions.png","tags":["Policies","3rd-Party","Producers"],"stages":["Beta"],"research":null,"strategies":["apis-have-clear-business-models","apis-have-clear-service-level-commitments","apis-scale-efficiently-under-load"],"experiences":["Money","Onboarding","Access"],"properties":["Plans"],"author":"Kin Lane"},{"name":"Time Frame","slug":"plan-time-frame","description":"Breaking down usage by seconds, minutes, days, or months gives consumers a clear picture of how their consumption is measured. This is basic transparency that too many APIs get wrong.","scope":"Business Contract","property":"none","type":"Breaking down usage by seconds, minutes, days, or months gives consumers a clear picture of how their consumption is measured. This is basic transparency that too many APIs get wrong.","guidance":"","image":"/images/time-frame.png","tags":["Policies","3rd-Party","Producers"],"stages":["Beta"],"research":null,"strategies":["apis-have-clear-business-models","apis-have-clear-service-level-commitments"],"experiences":["Money","Onboarding","Access"],"properties":["Plans"],"author":"Kin Lane"},{"name":"Plans","slug":"plans","description":"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.","scope":"Business Contract","property":"none","type":"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.","guidance":"onboarding/plans","image":"/images/plans.png","tags":["Policies","3rd-Party","Producers"],"experiences":["Alignment","Communication","Onboarding","Access","Simplicity","Consistency","Money"],"rules":["apis-json-apis-properties-plans-info"],"stages":["Beta","Default"],"research":null,"strategies":["apis-have-clear-business-models","apis-have-clear-service-level-commitments","onboarding-is-always-as-easy-as-possible"],"properties":["Plans","Pricing"],"author":"Kin Lane"},{"name":"Policies","slug":"policies","description":"Policies connect the machine-readable rules to the business reasons behind them. This is how you organize governance around what actually matters to the organization, not just technical checkboxes.","scope":"Business Contract","property":"none","type":"Policies connect the machine-readable rules to the business reasons behind them. This is how you organize governance around what actually matters to the organization, not just technical checkboxes.","guidance":"governance/policies","image":"/images/policies.png","tags":["Support","3rd-Party","Producers"],"policies":["None"],"rules":["apis-json-apis-properties-policies-info"],"stages":["Define","Default"],"research":null,"strategies":["api-maturity-is-measured-and-improved"],"experiences":["Governance","Consistency","Quality"],"author":"Kin Lane"},{"name":"Portals","slug":"portals","description":"Developer portals bring together documentation, sign-up, getting started, plans, and SDKs in one place. Whether public or private, a dedicated portal is how you make the API experience accessible.","scope":"Business Contract","property":"none","type":"Developer portals bring together documentation, sign-up, getting started, plans, and SDKs in one place. Whether public or private, a dedicated portal is how you make the API experience accessible.","guidance":"portals/overview","image":"/images/portals.png","tags":["Portals"],"experiences":["Access","Alignment","Communication","Discovery","Onboarding","Self-Service"],"rules":["apis-json-apis-properties-portal-info"],"stages":["Production","Default"],"research":null,"strategies":["onboarding-is-always-as-easy-as-possible"],"properties":["Portals","Portal"],"author":"Kin Lane"},{"name":"Postman Collection","slug":"postman-collection","description":"Postman Collections give you an executable, machine-readable representation of your API. They make it possible to test, explore, and share API interactions in a way that OpenAPI alone does not cover.","scope":"Technical Contract","property":"none","type":"Postman Collections give you an executable, machine-readable representation of your API. They make it possible to test, explore, and share API interactions in a way that OpenAPI alone does not cover.","guidance":"contracts/collection","image":"/images/collections.png","tags":[],"experiences":["Access","Automation","Change","Consistency","Discovery","Onboarding","Self-Service"],"rules":["apis-json-apis-properties-postman-collection-info"],"stages":["Develop","Default"],"research":null,"strategies":["apis-are-defined-by-technical-contracts"],"properties":["PostmanCollection"],"author":"Kin Lane"},{"name":"Postman Workspace","slug":"postman-workspace","description":"Postman Workspaces provide a collaborative space for managing API contracts alongside GitHub. Private, partner, and public workspaces let you control access while keeping everything organized.","scope":"Business Contract","property":"none","type":"Postman Workspaces provide a collaborative space for managing API contracts alongside GitHub. Private, partner, and public workspaces let you control access while keeping everything organized.","guidance":"workspaces/postman-workspace","image":"/images/postman-workspace.png","tags":["Postman","Workspaces","Automation"],"experiences":["Access","Automation","Communication","Discovery","Onboarding","Self-Service","Workspaces","Collaboration"],"rules":["apis-json-apis-properties-postman-public-workspace-info"],"stages":["Define","Default"],"research":null,"strategies":["api-development-is-collaborative-across-teams","apis-operations-possess-dedicated-workspaces"],"properties":["PostmanPublicWorkspace","PostmanWorkspace"],"author":"Kin Lane"},{"name":"Privacy Policy","slug":"privacy-policy","description":"A privacy policy covering producers, consumers, and end-users is a legal building block that developers need to see before putting an API to work in their applications. It builds trust and covers liability.","scope":"Business Contract","property":"none","type":"A privacy policy covering producers, consumers, and end-users is a legal building block that developers need to see before putting an API to work in their applications. It builds trust and covers liability.","guidance":"legal/privacy-policy","image":"/images/privacy-policy.png","tags":["Policies","3rd-Party","Producers"],"policies":["None"],"experiences":["Reliability","Quality","Access","Legal","Compliance","Trust"],"rules":["apis-json-apis-properties-privacy-policy-info"],"stages":["Beta","Default"],"research":null,"strategies":["api-data-is-classified-and-protected","apis-are-legally-covered","apis-earn-and-maintain-consumer-trust","apis-meet-regulatory-and-compliance-requirements"],"properties":["PrivacyPolicy"],"author":"Kin Lane"},{"name":"Problem Details for HTTP APIs","slug":"problem-details-for-http-apis","description":"The Problem Details standard (RFC 7807) gives you a consistent way to structure error responses. Adopting it means consumers can handle errors programmatically instead of parsing custom formats for every API.","scope":"Technical Contract","property":"none","type":"The Problem Details standard (RFC 7807) gives you a consistent way to structure error responses. Adopting it means consumers can handle errors programmatically instead of parsing custom formats for every API.","guidance":"standards/problem-details-for-http-apis","image":"/images/errors.png","tags":["Policies","3rd-Party","Producers"],"rules":["openapi-components-responses-info","openapi-components-responses-bad-request-error","openapi-components-responses-bad-request-info","openapi-components-responses-conflict-error","openapi-components-responses-conflict-info","openapi-components-responses-error","openapi-components-responses-forbidden-error","openapi-components-responses-forbidden-info","openapi-components-responses-internal-server-error-error","openapi-components-responses-internal-server-error-info","openapi-components-responses-not-found-error","openapi-components-responses-not-found-info","openapi-components-responses-too-many-requests-error","openapi-components-responses-too-many-requests-info","openapi-components-responses-unauthorized-error","openapi-components-responses-unauthorized-info"],"stages":["Design","Default"],"research":null,"strategies":["api-errors-are-standardized-and-informative"],"experiences":["Quality","Reliability","Developer Experience","Interoperability"],"author":"Kin Lane"},{"name":"Certifications","slug":"provenance-certifications","description":"Certifications provide a formal record that an API contract has been reviewed and meets specific standards. This is how you build confidence that governance is not just theoretical.","scope":"Business Contract","property":"none","type":"Certifications provide a formal record that an API contract has been reviewed and meets specific standards. This is how you build confidence that governance is not just theoretical.","guidance":"","image":"/images/certifications.png","tags":["Policies","3rd-Party","Producers"],"stages":["Define"],"research":null,"strategies":["api-provenance-is-maintained-and-auditable"],"experiences":["Provenance","Quality","Trust","Compliance"],"properties":["GitHubRepository"],"author":"Kin Lane"},{"name":"Issues","slug":"provenance-issues","description":"Git issues create a paper trail of the conversations, decisions, and changes around an API contract. This provenance is valuable for auditing and understanding how an API got to where it is.","scope":"Business Contract","property":"none","type":"Git issues create a paper trail of the conversations, decisions, and changes around an API contract. This provenance is valuable for auditing and understanding how an API got to where it is.","guidance":"","image":"/images/issues.png","tags":["Policies","3rd-Party","Producers"],"stages":["Define"],"research":null,"strategies":["api-provenance-is-maintained-and-auditable"],"experiences":["Provenance","Quality","Trust","Compliance"],"properties":["GitHubRepository"],"author":"Kin Lane"},{"name":"Pull Requests","slug":"provenance-pull-requests","description":"Pull requests are where the actual changes to business and technical artifacts happen. They create a reviewable, traceable record of every modification to the API contract.","scope":"Business Contract","property":"none","type":"Pull requests are where the actual changes to business and technical artifacts happen. They create a reviewable, traceable record of every modification to the API contract.","guidance":"","image":"/images/pull-requests.png","tags":["Policies","3rd-Party","Producers"],"stages":["Define"],"research":null,"strategies":["api-provenance-is-maintained-and-auditable"],"experiences":["Provenance","Quality","Trust","Compliance"],"properties":["GitHubRepository"],"author":"Kin Lane"},{"name":"Reviews","slug":"provenance-reviews","description":"Governance reviews create a formal record of whether an API contract meets the standards. This is how you track compliance over time and build accountability into the process.","scope":"Business Contract","property":"none","type":"Governance reviews create a formal record of whether an API contract meets the standards. This is how you track compliance over time and build accountability into the process.","guidance":"","image":"/images/reviews.png","tags":["Policies","3rd-Party","Producers"],"stages":["Define"],"research":null,"strategies":["api-provenance-is-maintained-and-auditable"],"experiences":["Provenance","Quality","Trust","Compliance"],"properties":["GitHubRepository"],"author":"Kin Lane"},{"name":"Provenance","slug":"provenance","description":"Provenance is the story of how an API contract evolved over time. The reviews, validations, certifications, and conversations all contribute to a record that builds trust and supports auditing.","scope":"Business Contract","property":"none","type":"Provenance is the story of how an API contract evolved over time. The reviews, validations, certifications, and conversations all contribute to a record that builds trust and supports auditing.","guidance":"","image":"/images/provenance.png","tags":["Support","3rd-Party","Producers"],"experiences":["Provenance","Quality","Trust","Compliance"],"policies":["provenance-issues","provenance-pull-requests","provenance-reviews","provenance-certifications"],"stages":["Define"],"research":null,"strategies":["api-provenance-is-maintained-and-auditable"],"properties":["ChangeLog","GitHubRepository"],"author":"Kin Lane"},{"name":"Questions Issues","slug":"questions-issues","description":"Git issues are a solid way to handle questions about APIs. They create a searchable, public record of questions and answers that helps future consumers find what they need.","scope":"Business Contract","property":"none","type":"Git issues are a solid way to handle questions about APIs. They create a searchable, public record of questions and answers that helps future consumers find what they need.","guidance":"","image":"/images/issues.png","tags":["Policies","3rd-Party","Producers"],"rules":["apis-json-apis-properties-questions-issues-info"],"stages":["Define"],"research":null,"experiences":["Support","Communication"],"strategies":["apis-must-be-supported-and-have-feedback-loops"],"properties":["QuestionsGitHubIssues"],"author":"Kin Lane"},{"name":"Questions","slug":"questions","description":"Teams need a clear channel to ask questions about the API lifecycle, governance, and implementation details. Whether through issues, discussions, or email, the path to answers should be obvious.","scope":"Business Contract","property":"none","type":"Teams need a clear channel to ask questions about the API lifecycle, governance, and implementation details. Whether through issues, discussions, or email, the path to answers should be obvious.","guidance":"","image":"/images/questions.png","tags":["Support","3rd-Party","Producers"],"policies":["questions-issues"],"stages":["Define"],"research":null,"strategies":["api-development-is-collaborative-across-teams","apis-must-be-supported-and-have-feedback-loops"],"experiences":["Support","Communication"],"properties":["QuestionsGitHubIssues"],"author":"Kin Lane"},{"name":"Date","slug":"road-map-date","description":"A date on each road map item tells consumers when they can expect a change. Without dates, a road map is just a wish list with no accountability.","scope":"Business Contract","property":"none","type":"A date on each road map item tells consumers when they can expect a change. Without dates, a road map is just a wish list with no accountability.","guidance":"","image":"/images/dates.png","tags":["Properties","3rd-Party"],"stages":["Define"],"research":null,"experiences":["Change","Communication","Alignment"],"strategies":["change-is-actively-managed-for-each-api","api-change-is-relative-to-operational-change"],"properties":["RoadMap"],"author":"Kin Lane"},{"name":"Details","slug":"road-map-details","description":"The details on a road map entry describe what the proposed change actually involves. This is where consumers learn enough to start planning for what is coming.","scope":"Business Contract","property":"none","type":"The details on a road map entry describe what the proposed change actually involves. This is where consumers learn enough to start planning for what is coming.","guidance":"","image":"/images/descriptions.png","tags":["Properties","3rd-Party"],"stages":["Define"],"research":null,"experiences":["Change","Communication","Alignment"],"strategies":["change-is-actively-managed-for-each-api","api-change-is-relative-to-operational-change"],"properties":["RoadMap"],"author":"Kin Lane"},{"name":"Title","slug":"road-map-title","description":"A clear title on each road map item lets consumers quickly scan what is planned. Good titles communicate the essence of a change without requiring people to dig into the details.","scope":"Business Contract","property":"none","type":"A clear title on each road map item lets consumers quickly scan what is planned. Good titles communicate the essence of a change without requiring people to dig into the details.","guidance":"","image":"/images/names.png","tags":["Properties","3rd-Party"],"stages":["Define"],"research":null,"experiences":["Change","Communication","Alignment"],"strategies":["change-is-actively-managed-for-each-api","api-change-is-relative-to-operational-change"],"properties":["RoadMap"],"author":"Kin Lane"},{"name":"Version","slug":"road-map-version","description":"Tying road map items to a version tells consumers which release will include a given change. This connects planning to the versioning strategy and helps people prepare.","scope":"Business Contract","property":"none","type":"Tying road map items to a version tells consumers which release will include a given change. This connects planning to the versioning strategy and helps people prepare.","guidance":"","image":"/images/versions.png","tags":["Properties","3rd-Party"],"stages":["Define"],"research":null,"experiences":["Change","Communication","Alignment"],"strategies":["change-is-actively-managed-for-each-api","api-change-is-relative-to-operational-change"],"properties":["RoadMap"],"author":"Kin Lane"},{"name":"Road Map","slug":"road-map","description":"A road map is one of the most underrated building blocks of API operations. Even if nothing is planned, sharing that information builds trust. Consumers want to know what the future looks like.","scope":"Business Contract","property":"none","type":"A road map is one of the most underrated building blocks of API operations. Even if nothing is planned, sharing that information builds trust. Consumers want to know what the future looks like.","guidance":"change/road-map","image":"/images/road-maps.png","tags":["GitHub","Issues","Labels"],"experiences":["Alignment","Change","Communication","Consistency","Quality","Reliability"],"rules":["apis-json-apis-properties-road-map-info"],"stages":["Define","Default"],"research":null,"strategies":["api-change-is-relative-to-operational-change","change-is-actively-managed-for-each-api"],"properties":["RoadMap"],"author":"Kin Lane"},{"name":"Rules","slug":"rules","description":"Rules are the machine-readable backbone of API governance. They run in pipelines, lint contracts, and make sure each API meets the baseline. Making them part of the contract means governance scales.","scope":"Business Contract","property":"none","type":"Rules are the machine-readable backbone of API governance. They run in pipelines, lint contracts, and make sure each API meets the baseline. Making them part of the contract means governance scales.","guidance":"governance/rules","image":"/images/rules.png","tags":["Support","3rd-Party","Producers"],"policies":["None"],"stages":["Define","Default"],"research":null,"strategies":["api-maturity-is-measured-and-improved"],"experiences":["Governance","Consistency","Automation"],"author":"Kin Lane"},{"name":"CSharp","slug":"sdks-csharp","description":"Having a CSharp SDK available for each API means .NET developers can get up and running quickly. Meeting consumers where they are with their language of choice reduces friction.","scope":"Business Contract","property":"none","type":"Having a CSharp SDK available for each API means .NET developers can get up and running quickly. Meeting consumers where they are with their language of choice reduces friction.","guidance":"","image":"/images/csharp.png","tags":["Policies","3rd-Party","Producers"],"stages":["Beta"],"research":null,"experiences":["Onboarding","Developer Experience","Self-Service"],"strategies":["apis-work-across-multiple-programming-languages"],"properties":["SDKs"],"author":"Kin Lane"},{"name":"SDKs (Getting Started)","slug":"getting-started-sdks","description":"Including SDKs in your getting started flow gives consumers a head start. Pointing them to client libraries and code they can use right away removes a lot of friction from onboarding.","scope":"Business Contract","property":"none","type":"Including SDKs in your getting started flow gives consumers a head start. Pointing them to client libraries and code they can use right away removes a lot of friction from onboarding.","guidance":"","image":"/images/sdks.png","tags":["Policies","3rd-Party","Producers"],"stages":["Beta"],"research":null,"strategies":["apis-deliver-an-exceptional-developer-experience"],"experiences":["Onboarding","Self-Service","Developer Experience"],"properties":["GettingStarted","SDKs"],"author":"Kin Lane"},{"name":"Go","slug":"sdks-go","description":"A Go SDK gives consumers building in Go a native way to interact with the API. Language-specific SDKs are how you lower the barrier to entry across different developer communities.","scope":"Business Contract","property":"none","type":"A Go SDK gives consumers building in Go a native way to interact with the API. Language-specific SDKs are how you lower the barrier to entry across different developer communities.","guidance":"","image":"/images/go.png","tags":["Policies","3rd-Party","Producers"],"rules":["apis-json-apis-properties-sdk-go-info"],"stages":["Beta"],"research":null,"experiences":["Onboarding","Developer Experience","Self-Service"],"strategies":["apis-work-across-multiple-programming-languages"],"properties":["SDKs"],"author":"Kin Lane"},{"name":"Java","slug":"sdks-java","description":"Java SDKs are essential for reaching enterprise developers. Having a well-maintained Java client library shows that you take the enterprise segment of your consumer base seriously.","scope":"Business Contract","property":"none","type":"Java SDKs are essential for reaching enterprise developers. Having a well-maintained Java client library shows that you take the enterprise segment of your consumer base seriously.","guidance":"","image":"/images/java.png","tags":["Policies","3rd-Party","Producers"],"rules":["apis-json-apis-properties-sdk-java-info"],"stages":["Beta"],"research":null,"experiences":["Onboarding","Developer Experience","Self-Service"],"strategies":["apis-work-across-multiple-programming-languages"],"properties":["SDKs"],"author":"Kin Lane"},{"name":"JavaScript","slug":"sdks-javascript","description":"JavaScript SDKs cover both browser and Node.js consumers. Given how much of the web runs on JavaScript, having a solid SDK here is practically mandatory for broad adoption.","scope":"Business Contract","property":"none","type":"JavaScript SDKs cover both browser and Node.js consumers. Given how much of the web runs on JavaScript, having a solid SDK here is practically mandatory for broad adoption.","guidance":"","image":"/images/javascript.png","tags":["Policies","3rd-Party","Producers"],"rules":["apis-json-apis-properties-sdk-node-info"],"stages":["Beta"],"research":null,"experiences":["Onboarding","Developer Experience","Self-Service"],"strategies":["apis-work-across-multiple-programming-languages"],"properties":["SDKs"],"author":"Kin Lane"},{"name":"PHP","slug":"sdks-php","description":"PHP still powers a massive portion of the web. Having a PHP SDK available means you are not leaving a large segment of potential API consumers behind.","scope":"Business Contract","property":"none","type":"PHP still powers a massive portion of the web. Having a PHP SDK available means you are not leaving a large segment of potential API consumers behind.","guidance":"","image":"/images/php.png","tags":["Policies","3rd-Party","Producers"],"stages":["Beta"],"research":null,"experiences":["Onboarding","Developer Experience","Self-Service"],"strategies":["apis-work-across-multiple-programming-languages"],"properties":["SDKs"],"author":"Kin Lane"},{"name":"SDKs","slug":"sdks","description":"SDKs are how you meet developers where they are. Handling authentication, wrapping operations, and supporting multiple programming languages reduces the effort consumers need to get value from your API.","scope":"Business Contract","property":"none","type":"SDKs are how you meet developers where they are. Handling authentication, wrapping operations, and supporting multiple programming languages reduces the effort consumers need to get value from your API.","guidance":"code/software-development-kits","image":"/images/sdks.png","tags":["Policies","3rd-Party","Producers"],"experiences":["Alignment","Automation","Change","Consistency","Onboarding","Self-Service"],"rules":["apis-json-apis-properties-sdk-info"],"stages":["Beta","Default"],"research":null,"strategies":["apis-work-across-multiple-programming-languages","onboarding-is-always-as-easy-as-possible"],"properties":["SDKs"],"author":"Kin Lane"},{"name":"Authentication","slug":"security-authentication","description":"Authentication details should always travel with the API contract. I have seen too many situations where developers can find the docs but have no idea how to actually authenticate. That information needs to be front and center.","scope":"Business Contract","property":"none","type":"Authentication details should always travel with the API contract. I have seen too many situations where developers can find the docs but have no idea how to actually authenticate. That information needs to be front and center.","guidance":"","image":"/images/authentication.png","tags":["Policies","3rd-Party","Producers"],"stages":["Beta"],"research":null,"strategies":["api-authentication-is-standardized","api-authorization-is-properly-defined-and-enforced"],"experiences":["Security","Access","Trust","Onboarding"],"properties":["Authentication"],"author":"Kin Lane"},{"name":"OWASP","slug":"security-owasp-top-10","description":"The OWASP API Security Top Ten is a checklist I look for across the API landscape. Applying it is not optional -- it is the minimum bar for taking API security seriously.","scope":"Business Contract","property":"none","type":"The OWASP API Security Top Ten is a checklist I look for across the API landscape. Applying it is not optional -- it is the minimum bar for taking API security seriously.","guidance":"","image":"/images/owasp.png","tags":["Policies","3rd-Party","Producers"],"stages":["Beta"],"research":null,"strategies":["api-data-is-classified-and-protected"],"experiences":["Security","Trust","Quality"],"author":"Kin Lane"},{"name":"Testing","slug":"security-testing","description":"Security testing is where you prove that your security practices actually work. Publishing results builds confidence with consumers and catches vulnerabilities before they become incidents.","scope":"Business Contract","property":"none","type":"Security testing is where you prove that your security practices actually work. Publishing results builds confidence with consumers and catches vulnerabilities before they become incidents.","guidance":"","image":"/images/security.png","tags":["Policies","3rd-Party","Producers"],"stages":["Beta"],"research":null,"strategies":["apis-are-protected-from-abuse-and-misuse"],"experiences":["Security","Trust","Quality","Automation"],"author":"Kin Lane"},{"name":"Security","slug":"security","description":"Security is not a feature you bolt on at the end. It covers authentication, access management, testing, and certifications. Making it visible to consumers is how you build trust across the API landscape.","scope":"Business Contract","property":"none","type":"Security is not a feature you bolt on at the end. It covers authentication, access management, testing, and certifications. Making it visible to consumers is how you build trust across the API landscape.","guidance":"","image":"/images/security.png","tags":["Policies","3rd-Party","Producers"],"experiences":["Reliability","Quality","Change","Security","Access","Consistency"],"rules":["apis-json-apis-properties-security-info"],"stages":["Production","Default"],"research":null,"strategies":["operations-must-always-be-secure"],"author":"Kin Lane"},{"name":"GitHub Actions","slug":"source-of-truth-actions","description":"GitHub Actions turn your API delivery into a repeatable pipeline. Governance, validation, testing, and deployment all become automated steps that run consistently every time.","scope":"Business Contract","property":"none","type":"GitHub Actions turn your API delivery into a repeatable pipeline. Governance, validation, testing, and deployment all become automated steps that run consistently every time.","guidance":"repositories/github-actions","image":"/images/actions.png","tags":["Pull Requests","Commits"],"rules":["apis-json-apis-properties-github-action-info"],"stages":["Definition"],"research":null,"strategies":["api-delivery-is-fast-and-design-first","api-governance-is-automated-in-cicd","producing-apis-must-be-repeatable"],"experiences":["Provenance","Quality","Automation","Collaboration"],"properties":["GitHubActions"],"author":"Kin Lane"},{"name":"Issues","slug":"source-of-truth-issues","description":"Issues are how you communicate about API change and collect feedback in the open. They tie conversations directly to the repository where the actual artifacts live.","scope":"Business Contract","property":"none","type":"Issues are how you communicate about API change and collect feedback in the open. They tie conversations directly to the repository where the actual artifacts live.","guidance":"repositories/issues","image":"/images/issues.png","tags":["Issues"],"stages":["Definition"],"research":null,"strategies":["api-provenance-is-maintained-and-auditable"],"experiences":["Provenance","Quality","Automation","Collaboration"],"properties":["GitHubRepository"],"author":"Kin Lane"},{"name":"Pull Requests","slug":"source-of-truth-pull-requests","description":"Pull requests are the mechanism for submitting changes to business and technical artifacts. They create a reviewable, approvable workflow that keeps the source of truth clean.","scope":"Business Contract","property":"none","type":"Pull requests are the mechanism for submitting changes to business and technical artifacts. They create a reviewable, approvable workflow that keeps the source of truth clean.","guidance":"repositories/pull-requests","image":"/images/pull-requests.png","tags":["Pull Requests","Commits"],"stages":["Definition"],"research":null,"strategies":["api-provenance-is-maintained-and-auditable"],"experiences":["Provenance","Quality","Automation","Collaboration"],"properties":["GitHubRepository"],"author":"Kin Lane"},{"name":"README","slug":"source-of-truth-readme","description":"A README in each API contract repository is the front door for anyone landing there. It should tell you what the API is, how to find the contract, and where to get started.","scope":"Business Contract","property":"none","type":"A README in each API contract repository is the front door for anyone landing there. It should tell you what the API is, how to find the contract, and where to get started.","guidance":"repositories/readme","image":"/images/readme.png","tags":["README"],"stages":["Definition"],"research":null,"strategies":["api-provenance-is-maintained-and-auditable"],"experiences":["Provenance","Quality","Automation","Collaboration"],"properties":["GitHubRepository"],"author":"Kin Lane"},{"name":"Teams","slug":"source-of-truth-teams","description":"Using Git teams to control access to API contract repositories puts the right people in charge of the right APIs. It is a simple building block for managing access at scale.","scope":"Business Contract","property":"none","type":"Using Git teams to control access to API contract repositories puts the right people in charge of the right APIs. It is a simple building block for managing access at scale.","guidance":"repositories/teams","image":"/images/teams.png","tags":["Teams"],"stages":["Definition"],"research":null,"strategies":["api-provenance-is-maintained-and-auditable"],"experiences":["Provenance","Quality","Automation","Collaboration"],"properties":["GitHubOrganization"],"author":"Kin Lane"},{"name":"HTTP","slug":"standards-http","description":"HTTP from the IETF is the foundation that the entire API landscape is built on. Understanding and properly using HTTP is not optional -- it is the baseline for everything.","scope":"Standards","property":"none","type":"HTTP from the IETF is the foundation that the entire API landscape is built on. Understanding and properly using HTTP is not optional -- it is the baseline for everything.","guidance":"","image":"/images/http.png","tags":["Standards"],"stages":["Definition"],"research":null,"strategies":["apis-are-interoperable-across-systems"],"experiences":["Interoperability","Consistency","Quality"],"author":"Kin Lane"},{"name":"JSON Schema","slug":"standards-json-schema","description":"JSON Schema gives you a standard way to define and validate data models. It shows up everywhere in the API landscape -- in OpenAPI, in validation, and in contract testing.","scope":"Standards","property":"none","type":"JSON Schema gives you a standard way to define and validate data models. It shows up everywhere in the API landscape -- in OpenAPI, in validation, and in contract testing.","guidance":"","image":"/images/json-schema.png","tags":["Standards","Validation"],"stages":["Definition","Default"],"research":null,"strategies":["apis-are-interoperable-across-systems"],"experiences":["Interoperability","Consistency","Quality"],"author":"Kin Lane"},{"name":"JSON","slug":"standards-json","description":"JSON is the lingua franca of APIs. It is the format that most of the API landscape has settled on for exchanging data, and understanding its conventions matters.","scope":"Standards","property":"none","type":"JSON is the lingua franca of APIs. It is the format that most of the API landscape has settled on for exchanging data, and understanding its conventions matters.","guidance":"","image":"/images/json.png","tags":["Standards"],"stages":["Definition"],"research":null,"strategies":["apis-are-interoperable-across-systems"],"experiences":["Interoperability","Consistency","Quality"],"author":"Kin Lane"},{"name":"OpenAPI","slug":"standards-openapi","description":"OpenAPI is the specification I see driving the most consistency across the API landscape. It is the foundation for documentation, governance, code generation, and testing.","scope":"Standards","property":"none","type":"OpenAPI is the specification I see driving the most consistency across the API landscape. It is the foundation for documentation, governance, code generation, and testing.","guidance":"","image":"/images/openapi.png","tags":["Standards","Linux Foundation"],"stages":["Design","Default"],"research":null,"strategies":["apis-are-interoperable-across-systems"],"experiences":["Interoperability","Consistency","Quality"],"author":"Kin Lane"},{"name":"Spectral","slug":"standards-spectral","description":"Spectral is the linting engine I see most teams adopting for API governance. Defining rules in Spectral and running them in CI/CD is how governance becomes automated and scalable.","scope":"Standards","property":"none","type":"Spectral is the linting engine I see most teams adopting for API governance. Defining rules in Spectral and running them in CI/CD is how governance becomes automated and scalable.","guidance":"","image":"/images/spectral.png","tags":["Standards","Linting","Rules"],"stages":["Definition","Default"],"research":null,"experiences":["Interoperability","Consistency","Quality"],"strategies":["apis-are-aligned-with-industry-using-standards","apis-are-interoperable-across-systems"],"author":"Kin Lane"},{"name":"YAML","slug":"standards-yaml","description":"YAML is the format most people use for writing OpenAPI specs and configuration. It is more human-readable than JSON for authoring, which is why it has become the default in the API landscape.","scope":"Standards","property":"none","type":"YAML is the format most people use for writing OpenAPI specs and configuration. It is more human-readable than JSON for authoring, which is why it has become the default in the API landscape.","guidance":"","image":"/images/yaml.png","tags":["Standards"],"stages":["Definition","Default"],"research":null,"experiences":["Interoperability","Consistency","Quality"],"strategies":["apis-are-aligned-with-industry-using-standards","apis-are-interoperable-across-systems"],"author":"Kin Lane"},{"name":"Standards","slug":"standards","description":"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.","scope":"Business Contract","property":"none","type":"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.","guidance":"standards/overview","image":"/images/standards.png","tags":["Standards"],"policies":["standards-http","standards-json","standards-yaml","standards-openapi","standards-json-schema","standards-spectral","problem-details-for-http-apis","json-path"],"experiences":["Access","Alignment","Automation","Change","Communication","Consistency","Discovery","Legal","Onboarding","Quality","Reliability","Security","Self-Service","Simplicity"],"stages":["Definition","Default"],"research":null,"strategies":["apis-are-aligned-with-industry-using-standards","apis-are-interoperable-across-systems"],"author":"Kin Lane"},{"name":"Status Dashboard","slug":"status-dashboard","description":"A status dashboard gives consumers real-time visibility into whether an API is up and running. This is basic table stakes for any API that people depend on.","scope":"Business Contract","property":"none","type":"A status dashboard gives consumers real-time visibility into whether an API is up and running. This is basic table stakes for any API that people depend on.","guidance":"","image":"/images/dashboard.png","tags":["Testing"],"stages":["Beta","Default"],"research":null,"strategies":["apis-are-observable-and-monitored"],"experiences":["Reliability","Observability","Trust"],"properties":["Status"],"author":"Kin Lane"},{"name":"Status History","slug":"status-history","description":"Status history shows consumers the track record over time. Current status is important, but the historical pattern tells you whether an API is reliably available or constantly having issues.","scope":"Business Contract","property":"none","type":"Status history shows consumers the track record over time. Current status is important, but the historical pattern tells you whether an API is reliably available or constantly having issues.","guidance":"","image":"/images/history.png","tags":["Testing"],"stages":["Beta"],"research":null,"strategies":["apis-are-observable-and-monitored"],"experiences":["Reliability","Observability","Trust"],"properties":["Status"],"author":"Kin Lane"},{"name":"Status","slug":"status","description":"Status pages and monitoring reports are how you maintain trust with consumers. Showing current and historical uptime transparently is way more effective than pretending everything is always fine.","scope":"Business Contract","property":"none","type":"Status pages and monitoring reports are how you maintain trust with consumers. Showing current and historical uptime transparently is way more effective than pretending everything is always fine.","guidance":"monitoring/uptime","image":"/images/status.png","tags":["Policies","3rd-Party","Producers"],"experiences":["Automation","Communication","Quality","Reliability"],"rules":["apis-json-apis-properties-status-info"],"stages":["Beta","Default"],"research":null,"strategies":["apis-are-always-high-quality-and-reliable","apis-are-observable-and-monitored","apis-earn-and-maintain-consumer-trust","apis-have-clear-service-level-commitments"],"properties":["Status"],"author":"Kin Lane"},{"name":"Support Email","slug":"support-email","description":"Email support is the most basic support channel for an API. Having a dedicated email address where consumers can reach a real person is a minimum building block for any API program.","scope":"Business Contract","property":"none","type":"Email support is the most basic support channel for an API. Having a dedicated email address where consumers can reach a real person is a minimum building block for any API program.","guidance":"","image":"/images/email.png","tags":["Policies","3rd-Party","Producers"],"rules":["apis-json-apis-properties-support-email-info"],"stages":["Define","Default"],"research":null,"experiences":["Support","Communication"],"strategies":["apis-must-be-supported-and-have-feedback-loops"],"properties":["SupportEmail"],"author":"Kin Lane"},{"name":"Support Issues","slug":"support-issues","description":"Git issues as a support channel keep everything public, searchable, and tied to the source of truth. Other consumers benefit from seeing questions and answers in the open.","scope":"Business Contract","property":"none","type":"Git issues as a support channel keep everything public, searchable, and tied to the source of truth. Other consumers benefit from seeing questions and answers in the open.","guidance":"","image":"/images/issues.png","tags":["Policies","3rd-Party","Producers"],"rules":["apis-json-apis-properties-support-issues-info"],"stages":["Define","Default"],"research":null,"experiences":["Support","Communication"],"strategies":["apis-must-be-supported-and-have-feedback-loops"],"properties":["SupportGitHubIssues"],"author":"Kin Lane"},{"name":"Support","slug":"support","description":"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.","scope":"Business Contract","property":"none","type":"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.","guidance":"support/overview","image":"/images/support.png","tags":["Policies","3rd-Party","Producers"],"policies":["support-email","support-issues"],"experiences":["Alignment","Change","Communication","Consistency","Discovery","Quality","Reliability","Simplicity"],"rules":["apis-json-apis-properties-support-support-info"],"stages":["Define","Default"],"research":null,"strategies":["apis-must-be-supported-and-have-feedback-loops"],"properties":["Support","SupportEmail","SupportGitHubIssues"],"author":"Kin Lane"},{"name":"Teams","slug":"teams","description":"Every API needs someone owning it. Having at least one product and one engineering person actively responsible for an API throughout its lifecycle is how you prevent orphaned APIs from piling up.","scope":"Business Contract","property":"none","type":"Every API needs someone owning it. Having at least one product and one engineering person actively responsible for an API throughout its lifecycle is how you prevent orphaned APIs from piling up.","guidance":"organizations/teams","image":"/images/teams.png","tags":["Teams"],"rules":["apis-json-apis-properties-teams-info"],"stages":["Define","Default"],"research":null,"strategies":["api-development-is-collaborative-across-teams","apis-always-have-well-defined-owners-and-stakeholders"],"experiences":["Collaboration","Alignment","Communication"],"properties":["Teams"],"author":"Kin Lane"},{"name":"Technical Contract Validator","slug":"technical-contract-validator","description":"Validating the OpenAPI technical contract with linting rules gives you concrete feedback on where each API stands against your governance standards. This is governance made actionable.","scope":"Technical Contract","property":"none","type":"Validating the OpenAPI technical contract with linting rules gives you concrete feedback on where each API stands against your governance standards. This is governance made actionable.","guidance":"validator/overview","image":"/images/validator.png","tags":["Validation","Technical"],"rules":["apis-json-apis-properties-openapi-validator-info"],"stages":["Define"],"research":null,"strategies":["api-contracts-are-validated"],"experiences":["Quality","Consistency","Automation"],"author":"Kin Lane"},{"name":"Terms of Service","slug":"terms-of-service","description":"Terms of service define what consumers can and cannot do with your API. Making these front and center is how you cover the legal side of things and set clear expectations.","scope":"Business Contract","property":"none","type":"Terms of service define what consumers can and cannot do with your API. Making these front and center is how you cover the legal side of things and set clear expectations.","guidance":"legal/terms-of-service","image":"/images/terms-of-service.png","tags":["Policies","3rd-Party","Producers"],"policies":["None"],"experiences":["Change","Legal","Compliance","Trust"],"rules":["apis-json-apis-properties-terms-of-service-info"],"stages":["Beta","Default"],"research":null,"strategies":["apis-are-legally-covered","apis-earn-and-maintain-consumer-trust","apis-meet-regulatory-and-compliance-requirements"],"properties":["TermsOfService"],"author":"Kin Lane"},{"name":"Use Cases","slug":"use-cases","description":"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.","scope":"Business Contract","property":"none","type":"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.","guidance":"use-cases/overview","image":"/images/use-cases.png","tags":["Business"],"policies":["who","what","how","why"],"experiences":["Alignment","Change","Communication","Consistency","Discovery","Onboarding","Simplicity"],"rules":["apis-json-apis-properties-use-cases-info"],"stages":["Define","Default"],"research":null,"strategies":["apis-are-always-aligned-with-wider-enterprise","apis-have-clear-business-models"],"properties":["UseCases"],"author":"Kin Lane"},{"name":"Date-Based Versioning","slug":"versioning-date-base","description":"Date-based versioning ties API changes to specific calendar dates. I see this approach working well for APIs where consumers want predictable release schedules they can plan around.","scope":"Business Contract","property":"none","type":"Date-based versioning ties API changes to specific calendar dates. I see this approach working well for APIs where consumers want predictable release schedules they can plan around.","guidance":"","image":"/images/date-based-versioning.png","tags":["Properties","3rd-Party"],"stages":["Define"],"research":null,"strategies":["api-versioning-follows-a-defined-standard","breaking-changes-are-prevented-or-carefully-managed"],"experiences":["Change","Stability","Consistency","Trust"],"properties":["Versioning"],"author":"Kin Lane"},{"name":"Semantic Versioning","slug":"versioning-semantic-versioning","description":"Semantic versioning with major, minor, and patch numbers is the approach I see most often. It communicates the scope of change clearly -- breaking, feature, or fix.","scope":"Business Contract","property":"none","type":"Semantic versioning with major, minor, and patch numbers is the approach I see most often. It communicates the scope of change clearly -- breaking, feature, or fix.","guidance":"","image":"/images/semantic-versioning.png","tags":["Properties","3rd-Party"],"stages":["Define","Default"],"research":null,"strategies":["api-versioning-follows-a-defined-standard","breaking-changes-are-prevented-or-carefully-managed"],"experiences":["Change","Stability","Consistency","Trust"],"properties":["Versioning"],"author":"Kin Lane"},{"name":"Versioning","slug":"versioning","description":"Versioning is how you communicate change to consumers. Whether you use semantic or date-based, being explicit about your versioning strategy and sticking to it builds confidence that change is managed.","scope":"Business Contract","property":"none","type":"Versioning is how you communicate change to consumers. Whether you use semantic or date-based, being explicit about your versioning strategy and sticking to it builds confidence that change is managed.","guidance":"change/versioning","image":"/images/versions.png","tags":["Semantic Versioning","Date Based Versioning"],"policies":["versioning-semantic-versioning","versioning-date-base"],"experiences":["Alignment","Change","Communication","Consistency","Quality","Reliability"],"rules":["apis-json-apis-properties-versioning-info"],"stages":["Define","Default"],"research":null,"strategies":["api-change-is-relative-to-operational-change","api-versioning-follows-a-defined-standard","apis-are-gracefully-deprecated-and-retired","breaking-changes-are-prevented-or-carefully-managed"],"properties":["Versioning"],"author":"Kin Lane"},{"name":"Videos","slug":"videos","description":"Videos are an engaging way to demonstrate how an API works, share updates, and provide walkthroughs. They complement written docs and reach people who learn better by watching.","scope":"Business Contract","property":"none","type":"Videos are an engaging way to demonstrate how an API works, share updates, and provide walkthroughs. They complement written docs and reach people who learn better by watching.","guidance":"communication/videos","image":"/images/videos.png","tags":["Videos","Stories","Updates"],"experiences":["Alignment","Change","Communication","Consistency","Discovery","Onboarding","Self-Service"],"rules":["apis-json-apis-properties-video-info"],"stages":["Production","Default"],"research":null,"strategies":["apis-are-part-of-regular-active-communication"],"properties":["Videos"],"author":"Kin Lane"},{"name":"What Will Be Done With API","slug":"what","description":"Understanding what consumers will build with an API shapes everything from design to documentation. If you do not know what people will do with your resources, you are building in the dark.","scope":"Business Contract","property":"none","type":"Understanding what consumers will build with an API shapes everything from design to documentation. If you do not know what people will do with your resources, you are building in the dark.","guidance":"use-cases/what","image":"/images/what.png","tags":["Policies","3rd-Party","Producers"],"stages":["Define","Default"],"research":null,"strategies":["apis-have-clear-business-models"],"experiences":["Alignment","Discovery"],"author":"Kin Lane"},{"name":"Who Will Be Using API","slug":"who","description":"Knowing who is using your API -- the actual people and their contexts -- is fundamental. If you do not understand your consumers, you can not design an API that works for them.","scope":"Business Contract","property":"none","type":"Knowing who is using your API -- the actual people and their contexts -- is fundamental. If you do not understand your consumers, you can not design an API that works for them.","guidance":"use-cases/who","image":"/images/who.png","tags":["Policies","3rd-Party","Producers"],"stages":["Define","Default"],"research":null,"strategies":["apis-have-clear-business-models"],"experiences":["Alignment","Discovery"],"author":"Kin Lane"},{"name":"Why Will API Be Used","slug":"why","description":"The why behind API consumption is the business case. Understanding why consumers integrate with your API tells you whether you are delivering real value or just providing a technical capability nobody needs.","scope":"Business Contract","property":"none","type":"The why behind API consumption is the business case. Understanding why consumers integrate with your API tells you whether you are delivering real value or just providing a technical capability nobody needs.","guidance":"use-cases/why","image":"/images/why.png","tags":["Policies","3rd-Party","Producers"],"stages":["Define","Default"],"research":null,"strategies":["apis-have-clear-business-models"],"experiences":["Alignment","Discovery"],"author":"Kin Lane"},{"name":"Maintainers","slug":"maintainers","description":"Every API contract needs clear maintainer information. I want to know who is responsible for this API, who to contact when things break, and who is driving it forward.","scope":"Business Contract","property":"none","type":"Every API contract needs clear maintainer information. I want to know who is responsible for this API, who to contact when things break, and who is driving it forward.","guidance":"contracts/maintainers","image":"/images/maintainers.png","tags":["Contracts","People","Accountability"],"policies":["maintainers-name","maintainers-email"],"experiences":["Alignment","Communication","Support","Onboarding"],"rules":["apis-json-maintainers-info","apis-json-maintainers-fn-info","apis-json-maintainers-email-info"],"stages":["Define","Default"],"research":null,"strategies":["api-development-is-collaborative-across-teams"],"properties":["Teams"],"author":"Kin Lane"},{"name":"Maintainer Names","slug":"maintainers-name","description":"Putting a name on the maintainer makes accountability real. It is not just a team alias -- it is a human-readable reference to who is actually responsible for this API.","scope":"Business Contract","property":"fn","type":"Putting a name on the maintainer makes accountability real. It is not just a team alias -- it is a human-readable reference to who is actually responsible for this API.","guidance":"contracts/maintainers","image":"/images/maintainers.png","tags":["Contracts","People"],"experiences":["Collaboration","Support"],"rules":["apis-json-maintainers-fn-info"],"stages":["Define","Default"],"research":null,"strategies":["api-development-is-collaborative-across-teams"],"author":"Kin Lane"},{"name":"Maintainer Email","slug":"maintainers-email","description":"A maintainer email gives consumers and stakeholders a direct line to the person or team responsible. When something goes wrong or there is a question, this is how people reach out.","scope":"Business Contract","property":"email","type":"A maintainer email gives consumers and stakeholders a direct line to the person or team responsible. When something goes wrong or there is a question, this is how people reach out.","guidance":"contracts/maintainers","image":"/images/maintainers.png","tags":["Contracts","People"],"experiences":["Collaboration","Support"],"rules":["apis-json-maintainers-email-info"],"stages":["Define","Default"],"research":null,"strategies":["api-development-is-collaborative-across-teams"],"author":"Kin Lane"},{"name":"Centralizing Parameters Using Components","slug":"openapi-component-parameters","description":"Centralizing parameters in OpenAPI components is how you stop repeating yourself. Define a parameter once, reference it everywhere, and governance gets simpler.","scope":"API Contract","property":"none","type":"Centralizing parameters in OpenAPI components is how you stop repeating yourself. Define a parameter once, reference it everywhere, and governance gets simpler.","guidance":"openapi/components-parameters","image":"/images/parameters.png","tags":["OpenAPI","Components","Parameters"],"experiences":["Consistency","Quality","Reusability"],"rules":["openapi-components-parameters-error","openapi-components-parameters-info","openapi-components-parameters-description-error","openapi-components-parameters-description-info","openapi-components-parameters-name-error","openapi-components-parameters-name-info","openapi-components-parameters-schema-error","openapi-components-parameters-schema-info","openapi-components-parameters-in-error","openapi-components-parameters-in-info","openapi-components-parameters-casing-camel-error","openapi-components-parameters-casing-camel-info","openapi-parameters-componentized-error","openapi-parameters-componentized-info"],"stages":["Design","Develop"],"research":null,"strategies":["api-parameters-are-well-defined-and-consistent"],"author":"Kin Lane"},{"name":"Centralizing Responses Using Components","slug":"openapi-component-responses","description":"Putting common responses in OpenAPI components means your error patterns are defined once and used consistently. This is especially valuable for standardized error responses across all operations.","scope":"API Contract","property":"none","type":"Putting common responses in OpenAPI components means your error patterns are defined once and used consistently. This is especially valuable for standardized error responses across all operations.","guidance":"openapi/components-responses","image":"/images/responses.png","tags":["OpenAPI","Components","Responses"],"experiences":["Consistency","Quality","Reusability"],"rules":["openapi-components-responses-error","openapi-components-responses-info","openapi-components-responses-bad-request-error","openapi-components-responses-bad-request-info","openapi-components-responses-unauthorized-error","openapi-components-responses-unauthorized-info","openapi-components-responses-forbidden-error","openapi-components-responses-forbidden-info","openapi-components-responses-not-found-error","openapi-components-responses-not-found-info","openapi-components-responses-conflict-error","openapi-components-responses-conflict-info","openapi-components-responses-too-many-requests-error","openapi-components-responses-too-many-requests-info","openapi-components-responses-internal-server-error-error","openapi-components-responses-internal-server-error-info"],"stages":["Design","Develop"],"research":null,"strategies":["api-errors-are-standardized-and-informative"],"author":"Kin Lane"},{"name":"Centralizing Examples Using Components","slug":"openapi-component-examples","description":"Centralized examples in OpenAPI components give you realistic sample data that stays consistent across operations. They improve documentation quality and make mock servers actually useful.","scope":"API Contract","property":"none","type":"Centralized examples in OpenAPI components give you realistic sample data that stays consistent across operations. They improve documentation quality and make mock servers actually useful.","guidance":"openapi/components-examples","image":"/images/examples.png","tags":["OpenAPI","Components","Examples"],"experiences":["Consistency","Quality","Onboarding","Reusability","Developer Experience"],"rules":["openapi-components-examples-error","openapi-components-examples-info"],"stages":["Design","Develop"],"research":null,"strategies":["apis-must-reusable-whenever-possible"],"author":"Kin Lane"},{"name":"Schema Constraints","slug":"openapi-schema-constraints","description":"Schema constraints like min, max, minLength, maxLength, and enum values are the guardrails on your data. Without them, anything can flow through your API and garbage in means garbage out.","scope":"API Contract","property":"none","type":"Schema constraints like min, max, minLength, maxLength, and enum values are the guardrails on your data. Without them, anything can flow through your API and garbage in means garbage out.","guidance":"openapi/schema-constraints","image":"/images/schema.png","tags":["OpenAPI","Schema","Validation"],"experiences":["Quality","Reliability","Consistency"],"rules":["openapi-schema-properties-define-number-minimum-error","openapi-schema-properties-define-number-maximum-error","openapi-schema-properties-string-minlength-error","openapi-schema-properties-string-minlength-info","openapi-schema-properties-string-maxlength-error","openapi-schema-properties-string-maxlength-info","openapi-schema-properties-array-minitems-error","openapi-schema-properties-array-minitems-info","openapi-schema-properties-array-maxitems-error","openapi-schema-properties-array-maxitems-info","openapi-schema-properties-enum-casing-error","openapi-schema-properties-enum-casing-info","openapi-schema-properties-enum-info","openapi-schema-properties-allowed-integer-format-error","openapi-schema-properties-allowed-number-format-error"],"stages":["Design","Develop"],"research":null,"strategies":["data-should-be-well-defined-and-validated"],"author":"Kin Lane"},{"name":"Schema Required Properties","slug":"openapi-schema-required","description":"Marking required properties in your schema objects tells consumers and validators which fields must be present. This prevents incomplete data and makes API interactions predictable.","scope":"API Contract","property":"required","type":"Marking required properties in your schema objects tells consumers and validators which fields must be present. This prevents incomplete data and makes API interactions predictable.","guidance":"openapi/schema-required","image":"/images/schema.png","tags":["OpenAPI","Schema","Validation"],"experiences":["Quality","Reliability"],"rules":["openapi-schema-required-error","openapi-schema-required-info"],"stages":["Design","Develop"],"research":null,"strategies":["data-should-be-well-defined-and-validated"],"author":"Kin Lane"},{"name":"Path Trailing Slashes","slug":"openapi-path-trailing-slashes","description":"Trailing slashes on API paths cause more problems than people realize. Some tools treat /users and /users/ as different resources. Keeping paths clean prevents routing and caching issues.","scope":"API Contract","property":"none","type":"Trailing slashes on API paths cause more problems than people realize. Some tools treat /users and /users/ as different resources. Keeping paths clean prevents routing and caching issues.","guidance":"openapi/path-trailing-slashes","image":"/images/paths.png","tags":["OpenAPI","Paths","Naming"],"experiences":["Consistency","Interoperability"],"rules":["openapi-no-path-trailing-slash-error","openapi-no-path-trailing-slash-info"],"stages":["Design"],"research":null,"strategies":["apis-follow-consistent-design-patterns"],"author":"Kin Lane"},{"name":"Operation ID Conventions","slug":"openapi-operation-id-conventions","description":"Operation IDs need consistent conventions because code generators, SDKs, and docs all use them. Inconsistent casing or characters here breaks downstream tooling in ways that are painful to debug.","scope":"API Contract","property":"operationId","type":"Operation IDs need consistent conventions because code generators, SDKs, and docs all use them. Inconsistent casing or characters here breaks downstream tooling in ways that are painful to debug.","guidance":"openapi/operation-ids","image":"/images/operation-ids.png","tags":["OpenAPI","Operations","Naming"],"experiences":["Consistency","Quality","Developer Experience"],"rules":["openapi-operations-operation-ids-error","openapi-operations-operation-ids-info","openapi-operations-operation-ids-camel-case-error","openapi-operations-operation-ids-camel-case-info","openapi-operations-operation-ids-characters-error","openapi-operations-operation-ids-characters-info"],"stages":["Design","Develop"],"research":null,"strategies":["apis-follow-consistent-design-patterns"],"author":"Kin Lane"},{"name":"Deprecation","slug":"lifecycle-deprecation","description":"Deprecation is how you communicate that an API is on its way out. Having a clear policy for timelines, headers, and communication gives consumers the time they need to migrate without panic.","scope":"Business Contract","property":"none","type":"Deprecation is how you communicate that an API is on its way out. Having a clear policy for timelines, headers, and communication gives consumers the time they need to migrate without panic.","guidance":"lifecycle/deprecation","image":"/images/deprecation.png","tags":["Lifecycle","Change","Communication"],"experiences":["Alignment","Change","Communication","Reliability","Trust","Stability"],"rules":["apis-json-apis-properties-deprecation-policy-info","openapi-deprecation-sunset-header-error","openapi-deprecation-sunset-header-info","openapi-deprecation-description-error","openapi-deprecation-description-info"],"stages":["Production","Retiring"],"research":null,"strategies":["apis-are-gracefully-deprecated-and-retired","apis-earn-and-maintain-consumer-trust"],"properties":["DeprecationPolicy"],"author":"Kin Lane"},{"name":"Breaking Changes","slug":"lifecycle-breaking-changes","description":"Breaking changes are the thing consumers fear most. Defining what counts as breaking, how it gets reviewed, and how it gets communicated is essential for maintaining trust across the API landscape.","scope":"Business Contract","property":"none","type":"Breaking changes are the thing consumers fear most. Defining what counts as breaking, how it gets reviewed, and how it gets communicated is essential for maintaining trust across the API landscape.","guidance":"lifecycle/breaking-changes","image":"/images/breaking-changes.png","tags":["Lifecycle","Change","Versioning"],"experiences":["Alignment","Change","Communication","Reliability","Trust","Stability"],"stages":["Design","Production"],"research":null,"strategies":["api-dependencies-are-tracked-and-managed","api-versioning-follows-a-defined-standard","apis-are-gracefully-deprecated-and-retired","apis-earn-and-maintain-consumer-trust","breaking-changes-are-prevented-or-carefully-managed"],"author":"Kin Lane"},{"name":"Change Management","slug":"lifecycle-change-management","description":"Change management defines the review gates and approval workflows for API modifications. Without it, changes ship without anyone checking for impact, compatibility, or alignment with governance.","scope":"Business Contract","property":"none","type":"Change management defines the review gates and approval workflows for API modifications. Without it, changes ship without anyone checking for impact, compatibility, or alignment with governance.","guidance":"lifecycle/change-management","image":"/images/change-management.png","tags":["Lifecycle","Change","Governance"],"experiences":["Alignment","Change","Communication","Consistency","Quality","Governance"],"stages":["Design","Develop","Production"],"research":null,"strategies":["api-dependencies-are-tracked-and-managed","breaking-changes-are-prevented-or-carefully-managed"],"author":"Kin Lane"},{"name":"API Retirement","slug":"lifecycle-retirement","description":"Retirement is the end of an API's life, and it needs to be handled with the same care as the launch. Clear timelines, communication, and migration support make the difference between a clean shutdown and angry consumers.","scope":"Business Contract","property":"none","type":"Retirement is the end of an API's life, and it needs to be handled with the same care as the launch. Clear timelines, communication, and migration support make the difference between a clean shutdown and angry consumers.","guidance":"lifecycle/retirement","image":"/images/retirement.png","tags":["Lifecycle","Change","Communication"],"experiences":["Alignment","Change","Communication","Trust"],"stages":["Retiring"],"research":null,"strategies":["apis-are-gracefully-deprecated-and-retired"],"author":"Kin Lane"},{"name":"Authorization","slug":"security-authorization","description":"Authorization is where you define what authenticated consumers can actually do. RBAC, ABAC, and permission models determine the boundaries of access, and getting this right is critical.","scope":"","property":"","type":"Authorization is where you define what authenticated consumers can actually do. RBAC, ABAC, and permission models determine the boundaries of access, and getting this right is critical.","guidance":"security/authorization","image":"/images/authorization.png","tags":["Security","Access","Policies"],"experiences":["Access","Trust","Reliability","Security"],"stages":["Design","Develop"],"research":null,"strategies":["api-authorization-is-properly-defined-and-enforced"],"properties":["Authentication","OAuthScopes"],"author":"Kin Lane"},{"name":"Data Classification","slug":"security-data-classification","description":"Data classification is about knowing what you are exposing through your APIs. PII, financial data, internal data -- each has different handling requirements, and the classification drives those decisions.","scope":"","property":"","type":"Data classification is about knowing what you are exposing through your APIs. PII, financial data, internal data -- each has different handling requirements, and the classification drives those decisions.","guidance":"security/data-classification","image":"/images/data-classification.png","tags":["Security","Data","Compliance"],"experiences":["Trust","Compliance","Security","Legal"],"stages":["Design","Develop"],"research":null,"strategies":["api-data-is-classified-and-protected","apis-meet-regulatory-and-compliance-requirements"],"properties":["DataClassification"],"author":"Kin Lane"},{"name":"Transport Security","slug":"security-transport","description":"Transport security is non-negotiable. All API communication should happen over TLS with proper versions and cipher suites. This is the baseline for protecting data in transit.","scope":"","property":"","type":"Transport security is non-negotiable. All API communication should happen over TLS with proper versions and cipher suites. This is the baseline for protecting data in transit.","guidance":"security/transport","image":"/images/encryption.png","tags":["Security","Encryption","Infrastructure"],"experiences":["Trust","Reliability","Security","Compliance"],"stages":["Develop","Production"],"research":null,"strategies":["api-data-is-classified-and-protected","apis-earn-and-maintain-consumer-trust"],"author":"Kin Lane"},{"name":"Input Validation","slug":"security-input-validation","description":"Input validation is your first line of defense. Checking every parameter, header, and payload for type, format, and range prevents injection attacks and data corruption before they start.","scope":"","property":"","type":"Input validation is your first line of defense. Checking every parameter, header, and payload for type, format, and range prevents injection attacks and data corruption before they start.","guidance":"security/input-validation","image":"/images/validation.png","tags":["Security","Validation","OWASP"],"experiences":["Trust","Reliability","Quality","Security"],"stages":["Design","Develop"],"research":null,"strategies":["api-data-is-classified-and-protected"],"author":"Kin Lane"},{"name":"CORS","slug":"security-cors","description":"CORS policies control which origins can access your APIs from web browsers. Getting this wrong either blocks legitimate consumers or opens your APIs up to unauthorized cross-origin requests.","scope":"","property":"","type":"CORS policies control which origins can access your APIs from web browsers. Getting this wrong either blocks legitimate consumers or opens your APIs up to unauthorized cross-origin requests.","guidance":"security/cors","image":"/images/cors.png","tags":["Security","Access","Web"],"experiences":["Access","Trust","Security"],"stages":["Design","Develop"],"research":null,"strategies":["api-data-is-classified-and-protected"],"author":"Kin Lane"},{"name":"API Abuse Prevention","slug":"security-abuse-prevention","description":"Abuse prevention goes beyond rate limiting into throttling, quotas, circuit breakers, and bot detection. These mechanisms protect API stability and availability for the consumers who are using things legitimately.","scope":"","property":"","type":"Abuse prevention goes beyond rate limiting into throttling, quotas, circuit breakers, and bot detection. These mechanisms protect API stability and availability for the consumers who are using things legitimately.","guidance":"security/abuse-prevention","image":"/images/abuse-prevention.png","tags":["Security","Performance","Infrastructure"],"experiences":["Trust","Reliability","Security","Scalability"],"stages":["Develop","Production"],"research":null,"strategies":["apis-are-protected-from-abuse-and-misuse"],"author":"Kin Lane"},{"name":"Monitoring","slug":"operations-monitoring","description":"Monitoring is how you know if your APIs are actually working the way they should. SLIs, SLOs, alerting thresholds, and dashboards are the building blocks for catching problems before your consumers do.","scope":"Business Contract","property":"none","type":"Monitoring is how you know if your APIs are actually working the way they should. SLIs, SLOs, alerting thresholds, and dashboards are the building blocks for catching problems before your consumers do.","guidance":"operations/monitoring","image":"/images/monitoring.png","tags":["Operations","Observability","Performance"],"experiences":["Reliability","Quality","Trust","Observability"],"stages":["Develop","Production","Default"],"research":null,"strategies":["apis-are-observable-and-monitored"],"properties":["Monitoring"],"author":"Kin Lane"},{"name":"Logging","slug":"operations-logging","description":"Logging gives you the record of what happened with every API interaction. Request and response logs, audit trails, and retention policies are essential for debugging, security, and compliance.","scope":"Business Contract","property":"none","type":"Logging gives you the record of what happened with every API interaction. Request and response logs, audit trails, and retention policies are essential for debugging, security, and compliance.","guidance":"operations/logging","image":"/images/logging.png","tags":["Operations","Observability","Compliance"],"experiences":["Reliability","Quality","Compliance","Observability","Provenance"],"stages":["Develop","Production"],"research":null,"strategies":["api-provenance-is-maintained-and-auditable","apis-are-observable-and-monitored","apis-meet-regulatory-and-compliance-requirements"],"properties":["Logging","AuditLogs"],"author":"Kin Lane"},{"name":"Caching","slug":"operations-caching","description":"Caching done right makes APIs faster and reduces load. Cache headers, TTL values, ETags, and invalidation strategies are the building blocks, but getting them wrong makes things worse, not better.","scope":"","property":"","type":"Caching done right makes APIs faster and reduces load. Cache headers, TTL values, ETags, and invalidation strategies are the building blocks, but getting them wrong makes things worse, not better.","guidance":"operations/caching","image":"/images/caching.png","tags":["Operations","Performance"],"experiences":["Performance","Quality","Scalability"],"rules":["openapi-caching-cache-control-header-error","openapi-caching-cache-control-header-info","openapi-caching-etag-header-error","openapi-caching-etag-header-info"],"stages":["Design","Develop"],"research":null,"strategies":["apis-scale-efficiently-under-load"],"properties":["Caching"],"author":"Kin Lane"},{"name":"Error Handling","slug":"operations-error-handling","description":"Standardized error handling using RFC 7807 Problem Details gives consumers a consistent way to handle errors across all your APIs. Consistent error codes, messages, and correlation IDs make debugging possible.","scope":"API Contract","property":"none","type":"Standardized error handling using RFC 7807 Problem Details gives consumers a consistent way to handle errors across all your APIs. Consistent error codes, messages, and correlation IDs make debugging possible.","guidance":"operations/error-handling","image":"/images/errors.png","tags":["Operations","Responses","Standards"],"experiences":["Quality","Reliability","Onboarding","Developer Experience","Interoperability"],"rules":["openapi-error-response-rfc7807-error","openapi-error-response-rfc7807-info","openapi-components-responses-bad-request-error","openapi-components-responses-bad-request-info","openapi-components-responses-unauthorized-error","openapi-components-responses-unauthorized-info","openapi-components-responses-forbidden-error","openapi-components-responses-forbidden-info","openapi-components-responses-not-found-error","openapi-components-responses-not-found-info","openapi-components-responses-internal-server-error-error","openapi-components-responses-internal-server-error-info"],"stages":["Design","Develop"],"research":null,"strategies":["api-errors-are-standardized-and-informative","apis-follow-consistent-design-patterns"],"properties":["Errors"],"author":"Kin Lane"},{"name":"Pagination","slug":"operations-pagination","description":"Pagination determines how consumers retrieve large datasets from your APIs. Whether you use cursor-based or offset-based, having a consistent approach with clear metadata is how you scale data access.","scope":"","property":"","type":"Pagination determines how consumers retrieve large datasets from your APIs. Whether you use cursor-based or offset-based, having a consistent approach with clear metadata is how you scale data access.","guidance":"operations/pagination","image":"/images/pagination.png","tags":["Operations","Design","Patterns"],"experiences":["Consistency","Quality","Onboarding","Developer Experience","Scalability","Performance"],"rules":["openapi-pagination-limit-parameter-info","openapi-pagination-offset-parameter-info","openapi-pagination-response-metadata-info"],"stages":["Design","Develop"],"research":null,"strategies":["apis-follow-consistent-design-patterns","apis-scale-efficiently-under-load"],"properties":["Pagination"],"author":"Kin Lane"},{"name":"Filtering and Sorting","slug":"operations-filtering-sorting","description":"Filtering and sorting conventions should be learned once and applied everywhere. Consistent query parameter patterns for filter, sort, and search make your APIs predictable across the board.","scope":"","property":"","type":"Filtering and sorting conventions should be learned once and applied everywhere. Consistent query parameter patterns for filter, sort, and search make your APIs predictable across the board.","guidance":"operations/filtering-sorting","image":"/images/filtering.png","tags":["Operations","Design","Patterns"],"experiences":["Consistency","Quality","Onboarding","Developer Experience"],"rules":["openapi-filtering-query-parameter-filter-info","openapi-sorting-query-parameter-sort-info"],"stages":["Design","Develop"],"research":null,"strategies":["apis-follow-consistent-design-patterns","apis-scale-efficiently-under-load"],"author":"Kin Lane"},{"name":"Health Checks","slug":"operations-health-checks","description":"Health check endpoints are what monitoring, load balancers, and orchestration tools use to know if an API is alive and ready. The response format and status indicators need to be standardized.","scope":"Business Contract","property":"none","type":"Health check endpoints are what monitoring, load balancers, and orchestration tools use to know if an API is alive and ready. The response format and status indicators need to be standardized.","guidance":"operations/health-checks","image":"/images/health-checks.png","tags":["Operations","Infrastructure","Observability"],"experiences":["Reliability","Quality","Observability"],"stages":["Develop","Production"],"research":null,"strategies":["apis-are-observable-and-monitored"],"author":"Kin Lane"},{"name":"Naming Conventions","slug":"design-naming-conventions","description":"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 navigate intuitively.","scope":"API Contract","property":"none","type":"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 navigate intuitively.","guidance":"design/naming-conventions","image":"/images/naming.png","tags":["Design","Naming","Consistency"],"experiences":["Consistency","Quality","Onboarding","Developer Experience","Simplicity"],"rules":["openapi-schema-names-pascal-case-error","openapi-schema-names-pascal-case-info","openapi-schema-properties-names-camel-case-error","openapi-schema-properties-names-camel-case-info","openapi-components-parameters-casing-camel-error","openapi-components-parameters-casing-camel-info","openapi-operations-operation-ids-camel-case-error","openapi-operations-operation-ids-camel-case-info"],"stages":["Design"],"research":null,"strategies":["apis-follow-consistent-design-patterns"],"author":"Kin Lane"},{"name":"Media Types","slug":"design-media-types","description":"Media types define the content formats your APIs support. JSON is the default I see across the landscape, but having a clear policy for content negotiation prevents confusion when multiple formats are in play.","scope":"API Contract","property":"none","type":"Media types define the content formats your APIs support. JSON is the default I see across the landscape, but having a clear policy for content negotiation prevents confusion when multiple formats are in play.","guidance":"design/media-types","image":"/images/media-types.png","tags":["Design","Standards","Content"],"experiences":["Consistency","Quality","Interoperability"],"rules":["openapi-request-bodies-application-json-info","openapi-request-bodies-application-x-www-form-url-encoded-info","openapi-response-get-200-media-type-error","openapi-response-get-200-media-type-info"],"stages":["Design"],"research":null,"strategies":["apis-are-interoperable-across-systems","apis-follow-consistent-design-patterns"],"properties":["MediaTypes"],"author":"Kin Lane"},{"name":"Idempotency","slug":"design-idempotency","description":"Idempotency is one of those design principles that separates reliable APIs from fragile ones. Knowing which operations are safe to retry and how idempotency keys work prevents duplicate processing and builds trust.","scope":"","property":"","type":"Idempotency is one of those design principles that separates reliable APIs from fragile ones. Knowing which operations are safe to retry and how idempotency keys work prevents duplicate processing and builds trust.","guidance":"design/idempotency","image":"/images/idempotency.png","tags":["Design","Patterns","Reliability"],"experiences":["Reliability","Quality","Trust"],"stages":["Design","Develop"],"research":null,"strategies":["apis-follow-consistent-design-patterns","apis-support-event-driven-and-asynchronous-patterns"],"author":"Kin Lane"},{"name":"Asynchronous and Webhook Patterns","slug":"design-async-webhooks","description":"Webhooks and async patterns are how APIs handle event-driven integrations. Registration, payload formats, retry policies, and delivery guarantees all need standards to keep these patterns reliable.","scope":"","property":"","type":"Webhooks and async patterns are how APIs handle event-driven integrations. Registration, payload formats, retry policies, and delivery guarantees all need standards to keep these patterns reliable.","guidance":"design/async-webhooks","image":"/images/webhooks.png","tags":["Design","Patterns","Events"],"experiences":["Consistency","Reliability","Quality","Interoperability"],"rules":["openapi-webhooks-object-info"],"stages":["Design","Develop"],"research":null,"strategies":["apis-support-event-driven-and-asynchronous-patterns"],"author":"Kin Lane"},{"name":"Hypermedia","slug":"design-hypermedia","description":"Hypermedia links in API responses let clients discover what actions are available dynamically. It reduces the coupling between clients and servers and makes APIs more self-describing and navigable.","scope":"","property":"","type":"Hypermedia links in API responses let clients discover what actions are available dynamically. It reduces the coupling between clients and servers and makes APIs more self-describing and navigable.","guidance":"design/hypermedia","image":"/images/hypermedia.png","tags":["Design","Patterns","Standards"],"experiences":["Consistency","Onboarding","Self-Service","Interoperability","Developer Experience"],"rules":["openapi-hypermedia-links-error","openapi-hypermedia-links-info"],"stages":["Design"],"research":null,"strategies":["apis-are-interoperable-across-systems","apis-support-event-driven-and-asynchronous-patterns"],"properties":["Hypermedia"],"author":"Kin Lane"},{"name":"Batch Operations","slug":"design-batch-operations","description":"Batch operations let consumers process multiple items in a single request. Defining how bulk requests work, how partial failures are handled, and what size limits apply keeps these patterns consistent and efficient.","scope":"","property":"","type":"Batch operations let consumers process multiple items in a single request. Defining how bulk requests work, how partial failures are handled, and what size limits apply keeps these patterns consistent and efficient.","guidance":"design/batch-operations","image":"/images/batch.png","tags":["Design","Patterns","Performance"],"experiences":["Quality","Performance","Scalability"],"stages":["Design","Develop"],"research":null,"strategies":["apis-scale-efficiently-under-load"],"author":"Kin Lane"},{"name":"API Catalog","slug":"experience-api-catalog","description":"An API catalog is the front door to your API program. If consumers can not discover and search for APIs with consistent metadata, they will never know what is available to them.","scope":"Business Contract","property":"none","type":"An API catalog is the front door to your API program. If consumers can not discover and search for APIs with consistent metadata, they will never know what is available to them.","guidance":"experience/api-catalog","image":"/images/catalog.png","tags":["Experience","Discovery","Portals"],"experiences":["Discovery","Onboarding","Self-Service"],"stages":["Define","Production","Default"],"research":null,"strategies":["apis-are-discoverable-through-a-central-catalog"],"properties":["OpenAPI","About"],"author":"Kin Lane"},{"name":"Sandbox Environments","slug":"experience-sandbox","description":"Sandbox environments let consumers explore and test APIs without any risk. Mock servers, sandbox credentials, and sample data are building blocks that accelerate onboarding and reduce integration time.","scope":"Business Contract","property":"none","type":"Sandbox environments let consumers explore and test APIs without any risk. Mock servers, sandbox credentials, and sample data are building blocks that accelerate onboarding and reduce integration time.","guidance":"experience/sandbox","image":"/images/sandbox.png","tags":["Experience","Testing","Onboarding"],"experiences":["Onboarding","Self-Service","Access","Developer Experience","Velocity"],"rules":["apis-json-apis-properties-sandbox-info","apis-json-apis-properties-environments-staging-info"],"stages":["Develop","Production"],"research":null,"strategies":["api-delivery-is-fast-and-design-first","apis-deliver-an-exceptional-developer-experience"],"properties":["Sandbox"],"author":"Kin Lane"},{"name":"Service Level Agreements","slug":"experience-sla","description":"SLAs make your reliability commitments formal and measurable. Uptime, latency, and throughput guarantees at each plan tier -- with real consequences for missing them -- are what separate serious API programs from hobbyist ones.","scope":"Business Contract","property":"none","type":"SLAs make your reliability commitments formal and measurable. Uptime, latency, and throughput guarantees at each plan tier -- with real consequences for missing them -- are what separate serious API programs from hobbyist ones.","guidance":"experience/sla","image":"/images/sla.png","tags":["Experience","Performance","Trust"],"experiences":["Trust","Reliability","Quality","Performance","Money"],"stages":["Production","Default"],"research":null,"strategies":["apis-earn-and-maintain-consumer-trust","apis-have-clear-service-level-commitments"],"properties":["SLA"],"author":"Kin Lane"},{"name":"Migration Guides","slug":"experience-migration-guides","description":"Migration guides are what consumers need when you ship a new version. Step-by-step instructions, breaking change summaries, and code examples make the difference between a smooth transition and a painful one.","scope":"Business Contract","property":"none","type":"Migration guides are what consumers need when you ship a new version. Step-by-step instructions, breaking change summaries, and code examples make the difference between a smooth transition and a painful one.","guidance":"experience/migration-guides","image":"/images/migration.png","tags":["Experience","Change","Documentation"],"experiences":["Change","Communication","Onboarding","Developer Experience","Stability"],"stages":["Production"],"research":null,"strategies":["api-versioning-follows-a-defined-standard","apis-are-gracefully-deprecated-and-retired","breaking-changes-are-prevented-or-carefully-managed"],"author":"Kin Lane"},{"name":"Interactive Documentation","slug":"experience-interactive-documentation","description":"Interactive documentation with try-it-out functionality lets consumers test API calls right from the docs. This removes the gap between reading about an API and actually experiencing how it works.","scope":"Business Contract","property":"none","type":"Interactive documentation with try-it-out functionality lets consumers test API calls right from the docs. This removes the gap between reading about an API and actually experiencing how it works.","guidance":"experience/interactive-documentation","image":"/images/interactive-docs.png","tags":["Experience","Documentation","Onboarding"],"experiences":["Onboarding","Self-Service","Discovery"],"stages":["Production","Default"],"research":null,"strategies":["apis-deliver-an-exceptional-developer-experience"],"properties":["InteractiveDocumentation"],"author":"Kin Lane"},{"name":"Localization","slug":"experience-localization","description":"Localization support in APIs means respecting Accept-Language headers, regional date formats, and translated messages. If your API serves a global audience, this is how you meet them where they are.","scope":"","property":"","type":"Localization support in APIs means respecting Accept-Language headers, regional date formats, and translated messages. If your API serves a global audience, this is how you meet them where they are.","guidance":"experience/localization","image":"/images/localization.png","tags":["Experience","Standards","Internationalization"],"experiences":["Onboarding","Quality","Interoperability","Scalability"],"stages":["Design","Develop"],"research":null,"strategies":["apis-deliver-an-exceptional-developer-experience"],"author":"Kin Lane"},{"name":"API Review and Approval","slug":"governance-review-approval","description":"API review and approval gates are where governance gets practical. Defining who reviews, what criteria matter, and how decisions are recorded keeps quality high without creating bottlenecks.","scope":"","property":"","type":"API review and approval gates are where governance gets practical. Defining who reviews, what criteria matter, and how decisions are recorded keeps quality high without creating bottlenecks.","guidance":"governance/review-approval","image":"/images/review.png","tags":["Governance","Process","Quality"],"experiences":["Alignment","Quality","Consistency","Governance","Collaboration"],"stages":["Design","Develop"],"research":null,"strategies":["api-development-is-collaborative-across-teams","api-maturity-is-measured-and-improved"],"author":"Kin Lane"},{"name":"Compliance Mapping","slug":"governance-compliance-mapping","description":"Mapping governance policies to regulatory requirements like GDPR, SOC2, and PCI-DSS connects API operations to legal obligations. This is how you prove compliance rather than just claiming it.","scope":"","property":"","type":"Mapping governance policies to regulatory requirements like GDPR, SOC2, and PCI-DSS connects API operations to legal obligations. This is how you prove compliance rather than just claiming it.","guidance":"governance/compliance-mapping","image":"/images/compliance.png","tags":["Governance","Compliance","Regulations"],"experiences":["Compliance","Trust","Alignment","Legal","Governance"],"stages":["Define","Design","Production"],"research":null,"strategies":["apis-meet-regulatory-and-compliance-requirements"],"author":"Kin Lane"},{"name":"Policy Exceptions","slug":"governance-policy-exceptions","description":"Policy exceptions are inevitable -- not every API fits every rule. Having a clear process for requesting, reviewing, and granting waivers keeps governance flexible without losing accountability.","scope":"","property":"","type":"Policy exceptions are inevitable -- not every API fits every rule. Having a clear process for requesting, reviewing, and granting waivers keeps governance flexible without losing accountability.","guidance":"governance/policy-exceptions","image":"/images/exceptions.png","tags":["Governance","Process"],"experiences":["Alignment","Quality","Governance","Velocity"],"stages":["Design","Develop","Production"],"research":null,"strategies":["apis-meet-regulatory-and-compliance-requirements"],"author":"Kin Lane"},{"name":"API Maturity Scoring","slug":"governance-maturity-scoring","description":"Maturity scoring gives you a measurable way to assess where each API stands across documentation, security, testing, and consumer experience. It turns governance from subjective opinions into trackable progress.","scope":"","property":"","type":"Maturity scoring gives you a measurable way to assess where each API stands across documentation, security, testing, and consumer experience. It turns governance from subjective opinions into trackable progress.","guidance":"governance/maturity-scoring","image":"/images/maturity.png","tags":["Governance","Quality","Metrics"],"experiences":["Alignment","Quality","Consistency","Governance"],"stages":["Define","Production","Default"],"research":null,"strategies":["api-maturity-is-measured-and-improved"],"author":"Kin Lane"},{"name":"API Dependency Management","slug":"governance-dependency-management","description":"API-to-API dependencies are something most organizations do not track until something breaks. Mapping upstream and downstream dependencies and requiring impact analysis is how you prevent cascading failures.","scope":"","property":"","type":"API-to-API dependencies are something most organizations do not track until something breaks. Mapping upstream and downstream dependencies and requiring impact analysis is how you prevent cascading failures.","guidance":"governance/dependency-management","image":"/images/dependencies.png","tags":["Governance","Architecture","Change"],"experiences":["Alignment","Change","Reliability","Observability","Stability"],"stages":["Design","Production"],"research":null,"strategies":["api-dependencies-are-tracked-and-managed"],"author":"Kin Lane"},{"name":"Linting in CI","slug":"cicd-linting","description":"Running linting rules in CI/CD is where governance becomes automated. Spectral rules, severity levels, and pass/fail decisions baked into the pipeline mean governance happens on every commit, not just during reviews.","scope":"","property":"","type":"Running linting rules in CI/CD is where governance becomes automated. Spectral rules, severity levels, and pass/fail decisions baked into the pipeline mean governance happens on every commit, not just during reviews.","guidance":"cicd/linting","image":"/images/linting.png","tags":["CI/CD","Automation","Governance"],"experiences":["Quality","Consistency","Automation","Governance"],"rules":["apis-json-apis-properties-github-action-info"],"stages":["Develop","Default"],"research":null,"strategies":["api-delivery-is-fast-and-design-first","api-governance-is-automated-in-cicd"],"properties":["Linting"],"author":"Kin Lane"},{"name":"Contract Testing","slug":"cicd-contract-testing","description":"Contract testing validates that the actual implementation matches the OpenAPI spec. Consumer-driven tests catch drift between the contract and reality before it breaks anyone's integration.","scope":"","property":"","type":"Contract testing validates that the actual implementation matches the OpenAPI spec. Consumer-driven tests catch drift between the contract and reality before it breaks anyone's integration.","guidance":"cicd/contract-testing","image":"/images/testing.png","tags":["CI/CD","Testing","Quality"],"experiences":["Quality","Reliability","Trust","Automation","Stability"],"stages":["Develop","Production"],"research":null,"strategies":["api-delivery-is-fast-and-design-first","api-governance-is-automated-in-cicd"],"properties":["ContractTesting"],"author":"Kin Lane"},{"name":"Schema Registry","slug":"cicd-schema-registry","description":"A schema registry centralizes your data models with versioning and compatibility checks. Publishing and consuming shared schemas from a registry reduces duplication and keeps data consistent across APIs.","scope":"","property":"","type":"A schema registry centralizes your data models with versioning and compatibility checks. Publishing and consuming shared schemas from a registry reduces duplication and keeps data consistent across APIs.","guidance":"cicd/schema-registry","image":"/images/schema-registry.png","tags":["CI/CD","Schema","Standards"],"experiences":["Consistency","Quality","Reusability","Interoperability"],"stages":["Design","Develop"],"research":null,"strategies":["api-delivery-is-fast-and-design-first","api-governance-is-automated-in-cicd"],"properties":["SchemaRegistry"],"author":"Kin Lane"},{"name":"API Mocking","slug":"cicd-api-mocking","description":"Mock servers generated from API contracts let consumers start integrating before the implementation is done. This is what design-first looks like in practice -- parallel development that actually works.","scope":"Business Contract","property":"none","type":"Mock servers generated from API contracts let consumers start integrating before the implementation is done. This is what design-first looks like in practice -- parallel development that actually works.","guidance":"cicd/api-mocking","image":"/images/mocking.png","tags":["CI/CD","Testing","Design"],"experiences":["Onboarding","Self-Service","Quality","Velocity","Collaboration"],"rules":["apis-json-apis-properties-mock-server-info"],"stages":["Design","Develop"],"research":null,"strategies":["api-delivery-is-fast-and-design-first","api-governance-is-automated-in-cicd"],"properties":["MockServer"],"author":"Kin Lane"},{"name":"Backwards Compatibility","slug":"design-compatibility","description":"Backwards compatibility is how you evolve APIs without breaking the consumers who already depend on them. Adding optional fields is fine. Removing or renaming published endpoints is not.","scope":"API Contract","property":"none","type":"Backwards compatibility is how you evolve APIs without breaking the consumers who already depend on them. Adding optional fields is fine. Removing or renaming published endpoints is not.","guidance":"design/compatibility","image":"/images/compatibility.png","tags":["Design","Compatibility","Lifecycle"],"experiences":["Stability","Interoperability","Trust","Change","Reliability"],"rules":["openapi-compatibility-additional-properties-info"],"stages":["Design","Production"],"research":null,"strategies":["apis-are-interoperable-across-systems","breaking-changes-are-prevented-or-carefully-managed"],"author":"Kin Lane"},{"name":"API-First Design","slug":"design-api-first","description":"API-first means the contract comes before the code. When the OpenAPI spec is the source of truth and consumer needs drive the design, you end up with better APIs that people actually want to use.","scope":"","property":"","type":"API-first means the contract comes before the code. When the OpenAPI spec is the source of truth and consumer needs drive the design, you end up with better APIs that people actually want to use.","guidance":"design/api-first","image":"/images/api-first.png","tags":["Design","Principles","Lifecycle"],"experiences":["Quality","Consistency","Velocity","Collaboration","Developer Experience"],"stages":["Define","Design"],"research":null,"strategies":["api-delivery-is-fast-and-design-first"],"author":"Kin Lane"},{"name":"Robustness Principle","slug":"design-robustness","description":"The robustness principle -- be liberal in what you accept, conservative in what you send -- is old wisdom that still applies. It keeps APIs forward-compatible and resilient to the messiness of real-world clients.","scope":"","property":"","type":"The robustness principle -- be liberal in what you accept, conservative in what you send -- is old wisdom that still applies. It keeps APIs forward-compatible and resilient to the messiness of real-world clients.","guidance":"design/robustness","image":"/images/robustness.png","tags":["Design","Principles","Compatibility"],"experiences":["Stability","Interoperability","Reliability","Quality"],"stages":["Design","Develop"],"research":null,"strategies":["apis-are-interoperable-across-systems","breaking-changes-are-prevented-or-carefully-managed"],"author":"Kin Lane"},{"name":"Long Running Operations","slug":"design-long-running-operations","description":"Long-running operations that can not complete synchronously need clear patterns. 202 Accepted responses, polling endpoints, and status reporting give consumers a consistent way to track async work.","scope":"","property":"","type":"Long-running operations that can not complete synchronously need clear patterns. 202 Accepted responses, polling endpoints, and status reporting give consumers a consistent way to track async work.","guidance":"design/long-running-operations","image":"/images/long-running.png","tags":["Design","Patterns","Async"],"experiences":["Reliability","Developer Experience","Consistency","Quality"],"rules":["openapi-long-running-202-status-code-info","openapi-long-running-retry-after-header-info"],"stages":["Design","Develop"],"research":null,"strategies":["apis-support-event-driven-and-asynchronous-patterns"],"author":"Kin Lane"},{"name":"OpenAPI Servers","slug":"openapi-servers","description":"Server objects in OpenAPI tell consumers where to find the API across environments. HTTPS URLs, meaningful descriptions, and sandbox/staging/production configurations are all essential here.","scope":"API Contract","property":"none","type":"Server objects in OpenAPI tell consumers where to find the API across environments. HTTPS URLs, meaningful descriptions, and sandbox/staging/production configurations are all essential here.","guidance":"openapi/servers","image":"/images/servers.png","tags":["OpenAPI","Servers","Infrastructure"],"experiences":["Access","Security","Onboarding","Developer Experience"],"rules":["openapi-servers-error","openapi-servers-info","openapi-servers-https-error","openapi-servers-https-info","openapi-servers-description-error","openapi-servers-description-info","openapi-servers-no-localhost-error"],"stages":["Design","Develop"],"research":null,"strategies":["apis-are-made-available-through-a-platform-gateway"],"author":"Kin Lane"},{"name":"Best Practices","slug":"design-best-practices","description":"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.","scope":"","property":"","type":"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.","guidance":"design/best-practices","image":"/images/best-practices.png","tags":["Design","Principles","Quality"],"experiences":["Quality","Consistency","Simplicity","Developer Experience","Onboarding"],"stages":["Design"],"research":null,"strategies":["apis-follow-consistent-design-patterns"],"author":"Kin Lane"},{"name":"HTTP Methods","slug":"openapi-http-methods","description":"HTTP methods have specific semantics -- GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes. Using them correctly is fundamental to building APIs that work the way consumers expect.","scope":"API Contract","property":"none","type":"HTTP methods have specific semantics -- GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes. Using them correctly is fundamental to building APIs that work the way consumers expect.","guidance":"openapi/http-methods","image":"/images/http-methods.png","tags":["OpenAPI","HTTP","Methods"],"experiences":["Consistency","Quality","Interoperability","Developer Experience"],"rules":["openapi-method-get-error","openapi-method-get-info","openapi-method-post-error","openapi-method-post-info","openapi-method-put-error","openapi-method-put-info","openapi-method-delete-error","openapi-method-delete-info","openapi-request-bodies-get-error","openapi-request-bodies-get-info","openapi-request-bodies-delete-error","openapi-request-bodies-delete-info"],"stages":["Design"],"research":null,"strategies":["apis-follow-consistent-design-patterns"],"author":"Kin Lane"},{"name":"HTTP Status Codes","slug":"openapi-http-status-codes","description":"Status codes are the language APIs use to communicate outcomes. Using 200, 201, 204, 400, 401, 403, 404, 429, and 500 correctly and consistently across operations is non-negotiable.","scope":"API Contract","property":"none","type":"Status codes are the language APIs use to communicate outcomes. Using 200, 201, 204, 400, 401, 403, 404, 429, and 500 correctly and consistently across operations is non-negotiable.","guidance":"openapi/http-status-codes","image":"/images/status-codes.png","tags":["OpenAPI","HTTP","Responses"],"experiences":["Consistency","Quality","Reliability","Developer Experience"],"policies":["openapi-operation-response-2xx","openapi-operation-response-4xx","openapi-operation-response-5xx"],"stages":["Design"],"research":null,"strategies":["apis-follow-consistent-design-patterns"],"author":"Kin Lane"},{"name":"Rate Limiting","slug":"operations-rate-limiting","description":"Rate limiting headers tell consumers where they stand with their usage. RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and Retry-After in responses let applications handle throttling gracefully.","scope":"API Contract","property":"none","type":"Rate limiting headers tell consumers where they stand with their usage. RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and Retry-After in responses let applications handle throttling gracefully.","guidance":"operations/rate-limiting","image":"/images/rate-limits.png","tags":["Operations","Performance","Headers"],"experiences":["Reliability","Developer Experience","Performance","Scalability","Trust"],"rules":["openapi-components-headers-rate-limit-error","openapi-components-headers-rate-limit-info","openapi-components-headers-retry-after-error","openapi-components-headers-retry-after-info"],"stages":["Design","Develop"],"research":null,"strategies":["apis-are-made-available-through-a-platform-gateway","apis-scale-efficiently-under-load"],"properties":["RateLimits"],"author":"Kin Lane"},{"name":"URL Structure","slug":"design-url-structure","description":"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 APIs.","scope":"API Contract","property":"none","type":"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 APIs.","guidance":"design/url-structure","image":"/images/paths.png","tags":["Design","Paths","Naming"],"experiences":["Consistency","Quality","Simplicity","Developer Experience","Interoperability"],"rules":["openapi-no-path-trailing-slash-error","openapi-no-path-trailing-slash-info","openapi-paths-declarations-error","openapi-paths-declarations-info","openapi-url-no-verbs-in-path-error","openapi-url-no-verbs-in-path-info","openapi-url-plural-resources-info","openapi-url-depth-limit-error"],"stages":["Design"],"research":null,"strategies":["apis-follow-consistent-design-patterns"],"author":"Kin Lane"},{"name":"Data Validation","slug":"design-validation","description":"Data validation at the API boundary catches problems before they propagate. Type checking, format enforcement, required fields, and enum validation are the building blocks of data integrity.","scope":"API Contract","property":"none","type":"Data validation at the API boundary catches problems before they propagate. Type checking, format enforcement, required fields, and enum validation are the building blocks of data integrity.","guidance":"design/validation","image":"/images/validation.png","tags":["Design","Validation","Schema"],"experiences":["Quality","Reliability","Security","Consistency"],"rules":["openapi-schema-required-error","openapi-schema-required-info","openapi-schema-type-error","openapi-schema-type-info"],"stages":["Design","Develop"],"research":null,"strategies":["apis-follow-consistent-design-patterns","data-should-be-well-defined-and-validated"],"author":"Kin Lane"},{"name":"Data Types and Formats","slug":"design-data-types","description":"Consistent data types across APIs prevent integration headaches. ISO 8601 for dates, standard number formats, and proper OpenAPI format specifiers mean data serializes the same way everywhere.","scope":"","property":"","type":"Consistent data types across APIs prevent integration headaches. ISO 8601 for dates, standard number formats, and proper OpenAPI format specifiers mean data serializes the same way everywhere.","guidance":"design/data-types","image":"/images/data-types.png","tags":["Design","Schema","Standards"],"experiences":["Consistency","Quality","Interoperability","Developer Experience"],"rules":["openapi-data-types-date-time-format-error","openapi-data-types-date-time-format-info"],"stages":["Design"],"research":null,"strategies":["apis-are-interoperable-across-systems","apis-follow-consistent-design-patterns","data-should-be-well-defined-and-validated"],"properties":["JSONSchema"],"author":"Kin Lane"}]

[{"name":"Access","slug":"access","image":"/images/access.png","description":"I keep seeing teams struggle with getting consumers proper access to their APIs. The sign-up, authentication, and authorization process is where you lose people before they ever make their first API call.","tags":["Solutions","Gateway","GatewayEnvironment"],"policies":["apis-json-url-info","authentication-jwt","authentication-keys","authentication-oauth","authentication-scopes","base-url","environments","experience-sandbox","gateway","github-organization","governance","human-url","login","openapi","openapi-operation-security","openapi-security","openapi-servers","plan-elements","plan-metrics","plan-rate-limits","plan-regions","plan-time-frame","plans","portals","postman-collection","postman-workspace","privacy-policy","security","security-authentication","security-authorization","security-cors","standards"],"strategies":["api-authentication-is-standardized","api-authorization-is-properly-defined-and-enforced","api-paths-must-conform-to-the-organization","api-responses-must-be-meaningful-and-consistent","apis-are-aligned-with-industry-using-standards","apis-are-defined-by-technical-contracts","apis-are-legally-covered","apis-are-made-available-through-a-platform-gateway","apis-have-clear-business-models","apis-have-one-click-access","apis-must-be-actively-governed","apis-must-reusable-whenever-possible","apis-operations-possess-dedicated-workspaces","data-should-be-well-defined-and-validated","operations-must-always-be-secure","operations-must-be-useful-and-consistent"],"properties":["Authentication","Gateway","Login","Signup","Sign-Up","Applications","Plans","Portal","Portals","StagingEnvironment","Sandbox","Environments"],"author":"Kin Lane"},{"name":"Alignment","slug":"alignment","image":"/images/alignment.png","description":"I see product and engineering teams talking past each other constantly when it comes to APIs. Without alignment on the why behind each API, you end up with technically sound resources that nobody actually needs.","tags":["Solutions"],"properties":["UseCases","Support","Forum","SupportGitHubIssues","SupportEmail","FeedbackGitHubIssues","FeedbackEmail","QuestionsGitHubIssues","Contributing","FAQs","StackExchange","ProfessinoalServices","Training","Partners"],"policies":["api-metadata","api-metadata-descriptions","api-metadata-images","api-metadata-names","api-metadata-tags","api-metadata-unique-identifiers","apis-json-created-info","apis-json-modified-info","blog-feeds","blogs","change-log","contract-metadata","contract-metadata-descriptions","contract-metadata-images","contract-metadata-names","contract-metadata-tags","contract-metadata-unique-identifiers","documentation","feedback","feedback-issues","governance","governance-api-rules","governance-compliance-mapping","governance-dependency-management","governance-lifecycle","governance-maturity-scoring","governance-operational-rules","governance-policies","governance-policy-exceptions","governance-review-approval","governance-vocabulary","how","lifecycle-breaking-changes","lifecycle-change-management","lifecycle-deprecation","lifecycle-retirement","maintainers","plans","portals","road-map","road-map-date","road-map-details","road-map-title","road-map-version","sdks","standards","support","teams","use-cases","versioning","videos","what","who","why"],"strategies":["api-change-is-relative-to-operational-change","api-contracts-are-validated","api-dependencies-are-tracked-and-managed","api-development-is-collaborative-across-teams","api-maturity-is-measured-and-improved","api-paths-must-conform-to-the-organization","apis-always-have-well-defined-owners-and-stakeholders","apis-are-aligned-with-industry-using-standards","apis-are-always-aligned-with-wider-enterprise","apis-are-always-well-documented","apis-are-defined-as-api-contracts","apis-are-discoverable-through-a-central-catalog","apis-are-gracefully-deprecated-and-retired","apis-are-legally-covered","apis-are-part-of-regular-active-communication","apis-have-clear-business-models","apis-meet-regulatory-and-compliance-requirements","apis-must-be-actively-governed","apis-must-be-supported-and-have-feedback-loops","apis-possess-informative-metadata","apis-work-across-multiple-programming-languages","breaking-changes-are-prevented-or-carefully-managed","change-is-actively-managed-for-each-api"],"author":"Kin Lane"},{"name":"Change","slug":"change","image":"/images/change.png","description":"Change is the one constant across the API landscape, and I watch teams struggle with it every single day. If you aren't actively managing and communicating change across versions, deprecations, and breaking updates, your consumers will find out the hard way.","tags":["Solutions"],"properties":["RoadMap","ChangeLog","Versioning"],"policies":["apis-json-created-info","apis-json-modified-info","blog-feeds","blogs","change-log","change-log-date","change-log-details","change-log-title","change-log-version","design-compatibility","experience-migration-guides","github-repository","governance","governance-dependency-management","licensing","lifecycle-breaking-changes","lifecycle-change-management","lifecycle-deprecation","lifecycle-retirement","openapi","openapi-version","postman-collection","road-map","road-map-date","road-map-details","road-map-title","road-map-version","sdks","security","standards","support","terms-of-service","use-cases","versioning","versioning-date-base","versioning-semantic-versioning","videos"],"strategies":["api-change-is-relative-to-operational-change","api-dependencies-are-tracked-and-managed","api-paths-must-conform-to-the-organization","api-versioning-follows-a-defined-standard","apis-always-have-well-defined-owners-and-stakeholders","apis-are-aligned-with-industry-using-standards","apis-are-always-aligned-with-wider-enterprise","apis-are-defined-by-technical-contracts","apis-are-gracefully-deprecated-and-retired","apis-are-made-available-through-a-platform-gateway","apis-are-part-of-regular-active-communication","apis-must-be-actively-governed","apis-must-be-supported-and-have-feedback-loops","apis-work-across-multiple-programming-languages","breaking-changes-are-prevented-or-carefully-managed","change-is-actively-managed-for-each-api","producing-apis-must-be-repeatable"],"author":"Kin Lane"},{"name":"Communication","slug":"communication","image":"/images/communication.png","description":"I struggle with how little communication happens between the teams producing APIs and the people consuming them. Blogs, changelogs, roadmaps -- these are building blocks that most teams just skip, and it shows.","tags":["Solutions"],"properties":["Teams","Blogs","Blog","BlogFeeds","Videos","News","Resources","WhitePapers","Webinars","CaseStudies","Events","LinkedIn","Reddit","Discord","Newsletter"],"policies":["api-metadata","api-metadata-descriptions","api-metadata-images","api-metadata-names","api-metadata-tags","api-metadata-unique-identifiers","apis-json-created-info","apis-json-modified-info","blog-feeds","blogs","change-log","change-log-date","change-log-details","change-log-title","change-log-version","contract-metadata","contract-metadata-descriptions","contract-metadata-images","contract-metadata-names","contract-metadata-tags","contract-metadata-unique-identifiers","documentation","experience-migration-guides","feedback","feedback-issues","getting-started","github-organization","github-repository","governance","lifecycle-breaking-changes","lifecycle-change-management","lifecycle-deprecation","lifecycle-retirement","maintainers","performance","plans","portals","postman-workspace","questions","questions-issues","road-map","road-map-date","road-map-details","road-map-title","road-map-version","standards","status","support","support-email","support-issues","teams","use-cases","versioning","videos"],"strategies":["api-change-is-relative-to-operational-change","api-contracts-are-validated","api-development-is-collaborative-across-teams","api-info-and-metadata-is-complete-and-accurate","api-paths-must-conform-to-the-organization","api-responses-must-be-meaningful-and-consistent","api-versioning-follows-a-defined-standard","apis-always-have-well-defined-owners-and-stakeholders","apis-are-aligned-with-industry-using-standards","apis-are-always-aligned-with-wider-enterprise","apis-are-always-high-quality-and-reliable","apis-are-always-well-documented","apis-are-defined-as-api-contracts","apis-are-gracefully-deprecated-and-retired","apis-are-legally-covered","apis-are-part-of-regular-active-communication","apis-earn-and-maintain-consumer-trust","apis-must-be-actively-governed","apis-must-be-supported-and-have-feedback-loops","apis-must-reusable-whenever-possible","apis-operations-possess-dedicated-workspaces","apis-possess-informative-metadata","breaking-changes-are-prevented-or-carefully-managed","change-is-actively-managed-for-each-api","data-should-be-well-defined-and-validated","onboarding-is-always-as-easy-as-possible","operations-must-always-be-secure","operations-must-be-useful-and-consistent","producing-apis-must-be-repeatable"],"author":"Kin Lane"},{"name":"Consistency","slug":"consistency","image":"/images/consistency.png","description":"When I look across the API landscape, consistency is one of the biggest challenges I see. Every team does things differently, and the surface area of inconsistency just grows until governance becomes impossible.","tags":["Solutions"],"properties":["OpenAPI","Policies","OperationalRules","ApiRules","Lifecycle","Vocabulary","Compliance","Extensions"],"policies":["apis-json-created-info","apis-json-modified-info","blog-feeds","blogs","business-contract-validator","change-log","cicd-linting","cicd-schema-registry","design-api-first","design-async-webhooks","design-best-practices","design-data-types","design-hypermedia","design-long-running-operations","design-media-types","design-naming-conventions","design-url-structure","design-validation","documentation","getting-started","github-repository","governance","governance-api-rules","governance-lifecycle","governance-maturity-scoring","governance-operational-rules","governance-policies","governance-review-approval","governance-vocabulary","json-path","licensing","lifecycle-change-management","openapi","openapi-component-examples","openapi-component-headers","openapi-component-parameters","openapi-component-responses","openapi-components","openapi-http-methods","openapi-http-status-codes","openapi-info-contact","openapi-info-description","openapi-info-license","openapi-info-terms-of-service","openapi-info-title","openapi-info-version","openapi-operation-id-conventions","openapi-operation-identifiers","openapi-operation-parameter-descriptions","openapi-operation-parameter-enum","openapi-operation-parameter-in","openapi-operation-parameter-names","openapi-operation-parameter-schema","openapi-operation-parameter-types","openapi-operation-parameters","openapi-operation-request-bodies","openapi-operation-request-bodies-examples","openapi-operation-request-bodies-media-types","openapi-operation-request-bodies-schema","openapi-operation-response-2xx","openapi-operation-response-4xx","openapi-operation-response-5xx","openapi-operation-tags","openapi-path-names","openapi-path-trailing-slashes","openapi-schema-constraints","openapi-schema-descriptions","openapi-schema-names","openapi-schema-properties","openapi-schema-property-descriptions","openapi-schema-property-names","openapi-schema-property-shapes","openapi-schema-property-types","openapi-schema-type","openapi-tags","openapi-version","operations-filtering-sorting","operations-pagination","plans","policies","postman-collection","road-map","rules","sdks","security","standards","standards-http","standards-json","standards-json-schema","standards-openapi","standards-spectral","standards-yaml","support","technical-contract-validator","use-cases","versioning","versioning-date-base","versioning-semantic-versioning","videos"],"strategies":["api-authentication-is-standardized","api-change-is-relative-to-operational-change","api-contracts-are-validated","api-errors-are-standardized-and-informative","api-governance-is-automated-in-cicd","api-info-and-metadata-is-complete-and-accurate","api-maturity-is-measured-and-improved","api-parameters-are-well-defined-and-consistent","api-paths-must-conform-to-the-organization","api-responses-must-be-meaningful-and-consistent","api-versioning-follows-a-defined-standard","apis-always-have-well-defined-owners-and-stakeholders","apis-are-aligned-with-industry-using-standards","apis-are-always-aligned-with-wider-enterprise","apis-are-always-well-documented","apis-are-defined-by-technical-contracts","apis-are-interoperable-across-systems","apis-are-legally-covered","apis-are-made-available-through-a-platform-gateway","apis-are-part-of-regular-active-communication","apis-follow-consistent-design-patterns","apis-must-be-actively-governed","apis-must-be-supported-and-have-feedback-loops","apis-must-reusable-whenever-possible","apis-support-event-driven-and-asynchronous-patterns","apis-work-across-multiple-programming-languages","breaking-changes-are-prevented-or-carefully-managed","change-is-actively-managed-for-each-api","data-should-be-well-defined-and-validated","onboarding-is-always-as-easy-as-possible","operations-must-always-be-secure","operations-must-be-useful-and-consistent","producing-apis-must-be-repeatable"],"author":"Kin Lane"},{"name":"Products","slug":"products","image":"/images/contracts.png","description":"I keep pushing teams to think of their APIs as products. When you treat an API like a product, you start thinking about who uses it, what they need, and how to make the whole thing sustainable.","tags":["Solutions"],"policies":["contract-metadata"],"strategies":["apis-have-clear-business-models"],"properties":["Plans","Pricing","UseCases","Documentation","SDKs","GettingStarted"],"author":"Kin Lane"},{"name":"Discovery","slug":"discovery","image":"/images/discovery.png","description":"Discovery is the dark matter of the API landscape. Teams build APIs that already exist somewhere else, and consumers can't find the APIs they need. Without a catalog and proper metadata, you're just building in the dark.","tags":["Solutions"],"policies":["api-metadata","api-metadata-descriptions","api-metadata-images","api-metadata-names","api-metadata-tags","api-metadata-unique-identifiers","blog-feeds","blogs","contract-metadata","contract-metadata-descriptions","contract-metadata-images","contract-metadata-names","contract-metadata-tags","contract-metadata-unique-identifiers","documentation","experience-api-catalog","experience-interactive-documentation","getting-started","github-organization","github-repository","governance","how","openapi","openapi-info-contact","openapi-info-description","openapi-info-license","openapi-info-terms-of-service","openapi-info-title","openapi-info-version","openapi-operation-tags","openapi-tags","portals","postman-collection","postman-workspace","standards","support","use-cases","videos","what","who","why"],"strategies":["api-info-and-metadata-is-complete-and-accurate","api-paths-must-conform-to-the-organization","api-responses-must-be-meaningful-and-consistent","apis-are-aligned-with-industry-using-standards","apis-are-always-aligned-with-wider-enterprise","apis-are-always-well-documented","apis-are-defined-as-api-contracts","apis-are-defined-by-technical-contracts","apis-are-discoverable-through-a-central-catalog","apis-are-made-available-through-a-platform-gateway","apis-are-part-of-regular-active-communication","apis-deliver-an-exceptional-developer-experience","apis-must-be-actively-governed","apis-must-be-supported-and-have-feedback-loops","apis-must-reusable-whenever-possible","apis-operations-possess-dedicated-workspaces","apis-possess-informative-metadata","data-should-be-well-defined-and-validated","onboarding-is-always-as-easy-as-possible","operations-must-always-be-secure","operations-must-be-useful-and-consistent","producing-apis-must-be-repeatable"],"properties":["About","Documentation","Portal","Portals","OpenAPI","PostmanCollection","Tags","Glossary"],"author":"Kin Lane"},{"name":"Legal","slug":"legal","image":"/images/legal.png","description":"The legal side of APIs is something most teams ignore until it bites them. Terms of service, privacy policies, licensing -- these building blocks matter, and the politics around API usage are only getting more intense.","tags":["Solutions"],"properties":["TermsOfService","PrivacyPolicy","InterfaceLicense"],"policies":["governance","governance-compliance-mapping","licensing","privacy-policy","security-data-classification","standards","terms-of-service"],"strategies":["api-data-is-classified-and-protected","apis-are-aligned-with-industry-using-standards","apis-are-legally-covered","apis-earn-and-maintain-consumer-trust","apis-meet-regulatory-and-compliance-requirements","apis-must-be-actively-governed"],"author":"Kin Lane"},{"name":"Onboarding","slug":"onboarding","image":"/images/onboarding.png","description":"I see teams dealing with massive friction during onboarding. If a consumer can't get from zero to their first successful API call in minutes, you've already lost them. Getting started guides, sandboxes, and clear documentation are the building blocks that make or break adoption.","tags":["Solutions"],"properties":["Portals","Portal","About","Documentation","GettingStarted","Guides","SDKs","Integrations","PostmanCollection","StagingEnvironment","Console","Sandbox","Pagination","Glossary","Sign-Up","Signup","Login","Applications","OpenSource"],"policies":["api-metadata","api-metadata-descriptions","api-metadata-images","api-metadata-names","api-metadata-tags","api-metadata-unique-identifiers","apis-json-url-info","authentication-jwt","authentication-keys","authentication-oauth","authentication-scopes","base-url","cicd-api-mocking","contract-metadata","design-best-practices","design-hypermedia","design-naming-conventions","documentation","documentation-examples","documentation-paths","documentation-request-bodies","documentation-responses","documentation-schema","environments","experience-api-catalog","experience-interactive-documentation","experience-localization","experience-migration-guides","experience-sandbox","getting-started","getting-started-authentication","getting-started-documentation","getting-started-sdks","github-organization","governance","guidance","guidance-business","guidance-people","guidance-policies","guidance-technical","human-url","licensing","login","maintainers","openapi","openapi-component-examples","openapi-external-docs","openapi-info-contact","openapi-info-description","openapi-info-license","openapi-info-terms-of-service","openapi-info-title","openapi-info-version","openapi-operation-description","openapi-operation-summary","openapi-servers","operations-error-handling","operations-filtering-sorting","operations-pagination","plan-elements","plan-metrics","plan-rate-limits","plan-regions","plan-time-frame","plans","portals","postman-collection","postman-workspace","sdks","sdks-csharp","sdks-go","sdks-java","sdks-javascript","sdks-php","security-authentication","standards","use-cases","videos"],"strategies":["api-authentication-is-standardized","api-errors-are-standardized-and-informative","api-info-and-metadata-is-complete-and-accurate","api-parameters-are-well-defined-and-consistent","api-paths-must-conform-to-the-organization","api-responses-must-be-meaningful-and-consistent","apis-always-have-well-defined-owners-and-stakeholders","apis-are-aligned-with-industry-using-standards","apis-are-always-aligned-with-wider-enterprise","apis-are-always-well-documented","apis-are-defined-as-api-contracts","apis-are-defined-by-technical-contracts","apis-are-discoverable-through-a-central-catalog","apis-are-legally-covered","apis-are-made-available-through-a-platform-gateway","apis-are-part-of-regular-active-communication","apis-deliver-an-exceptional-developer-experience","apis-follow-consistent-design-patterns","apis-have-clear-business-models","apis-have-one-click-access","apis-must-be-actively-governed","apis-must-reusable-whenever-possible","apis-operations-possess-dedicated-workspaces","apis-possess-informative-metadata","apis-work-across-multiple-programming-languages","data-should-be-well-defined-and-validated","onboarding-is-always-as-easy-as-possible","operations-must-always-be-secure","operations-must-be-useful-and-consistent"],"author":"Kin Lane"},{"name":"Provenance","slug":"provenance","image":"/images/provenance.png","description":"I keep shining a light on provenance because nobody talks about it enough. Where did this data come from? How has this resource evolved? Without tracking the source and history of your API resources, you're building on sand.","tags":["Solutions"],"policies":["change-log-date","change-log-details","change-log-title","change-log-version","github-repository","operations-logging","provenance","provenance-certifications","provenance-issues","provenance-pull-requests","provenance-reviews","source-of-truth-actions","source-of-truth-issues","source-of-truth-pull-requests","source-of-truth-readme","source-of-truth-teams"],"strategies":["api-provenance-is-maintained-and-auditable"],"properties":["ChangeLog","GitHubRepository","GitHubActions","AuditLogs","Versioning"],"author":"Kin Lane"},{"name":"Quality","slug":"quality","image":"/images/quality.png","description":"I see the quality of APIs eroding across the landscape. Teams ship fast and never look back, but consumers feel every rough edge, every missing example, every inconsistent response. Quality is what separates APIs people trust from ones they abandon.","tags":["Solutions"],"properties":["GitHubRepository"],"policies":["apis-json-created-info","apis-json-modified-info","business-contract-validator","change-log","cicd-api-mocking","cicd-contract-testing","cicd-linting","cicd-schema-registry","design-api-first","design-async-webhooks","design-batch-operations","design-best-practices","design-data-types","design-idempotency","design-long-running-operations","design-media-types","design-naming-conventions","design-robustness","design-url-structure","design-validation","documentation-examples","documentation-paths","documentation-request-bodies","documentation-responses","documentation-schema","experience-localization","experience-sla","github-repository","governance","governance-api-rules","governance-lifecycle","governance-maturity-scoring","governance-operational-rules","governance-policies","governance-policy-exceptions","governance-review-approval","governance-vocabulary","guidance","guidance-business","guidance-people","guidance-policies","guidance-technical","json-path","lifecycle-change-management","openapi-component-examples","openapi-component-headers","openapi-component-parameters","openapi-component-responses","openapi-components","openapi-http-methods","openapi-http-status-codes","openapi-info-contact","openapi-info-description","openapi-info-license","openapi-info-terms-of-service","openapi-info-title","openapi-info-version","openapi-operation-description","openapi-operation-id-conventions","openapi-operation-identifiers","openapi-operation-parameter-descriptions","openapi-operation-parameter-enum","openapi-operation-parameter-in","openapi-operation-parameter-names","openapi-operation-parameter-schema","openapi-operation-parameter-types","openapi-operation-parameters","openapi-operation-request-bodies","openapi-operation-request-bodies-examples","openapi-operation-request-bodies-media-types","openapi-operation-request-bodies-schema","openapi-operation-response-2xx","openapi-operation-response-4xx","openapi-operation-response-5xx","openapi-operation-summary","openapi-schema-constraints","openapi-schema-descriptions","openapi-schema-names","openapi-schema-properties","openapi-schema-property-descriptions","openapi-schema-property-names","openapi-schema-property-shapes","openapi-schema-property-types","openapi-schema-required","openapi-schema-type","operations-caching","operations-error-handling","operations-filtering-sorting","operations-health-checks","operations-logging","operations-monitoring","operations-pagination","performance","policies","privacy-policy","problem-details-for-http-apis","provenance","provenance-certifications","provenance-issues","provenance-pull-requests","provenance-reviews","road-map","security","security-input-validation","security-owasp-top-10","security-testing","source-of-truth-actions","source-of-truth-issues","source-of-truth-pull-requests","source-of-truth-readme","source-of-truth-teams","standards","standards-http","standards-json","standards-json-schema","standards-openapi","standards-spectral","standards-yaml","status","support","technical-contract-validator","versioning"],"strategies":["api-change-is-relative-to-operational-change","api-contracts-are-validated","api-delivery-is-fast-and-design-first","api-errors-are-standardized-and-informative","api-governance-is-automated-in-cicd","api-info-and-metadata-is-complete-and-accurate","api-maturity-is-measured-and-improved","api-parameters-are-well-defined-and-consistent","api-provenance-is-maintained-and-auditable","api-responses-must-be-meaningful-and-consistent","apis-always-have-well-defined-owners-and-stakeholders","apis-are-aligned-with-industry-using-standards","apis-are-always-high-quality-and-reliable","apis-are-interoperable-across-systems","apis-are-legally-covered","apis-are-made-available-through-a-platform-gateway","apis-are-observable-and-monitored","apis-deliver-an-exceptional-developer-experience","apis-follow-consistent-design-patterns","apis-have-clear-service-level-commitments","apis-must-be-actively-governed","apis-must-be-supported-and-have-feedback-loops","apis-must-reusable-whenever-possible","apis-scale-efficiently-under-load","apis-support-event-driven-and-asynchronous-patterns","change-is-actively-managed-for-each-api","data-should-be-well-defined-and-validated","operations-must-always-be-secure","operations-must-be-useful-and-consistent","producing-apis-must-be-repeatable"],"author":"Kin Lane"},{"name":"Reliability","slug":"reliability","image":"/images/reliability.png","description":"Reliability is where the rubber meets the road in the API landscape. If your APIs aren't up when consumers need them, and if new versions don't land smoothly, none of the other building blocks matter.","tags":["Solutions"],"properties":["GitHubActions","OperationalValidation","Performance","APIValidation","Status","Headers","Issues","Errors","RateLimits"],"policies":["apis-json-created-info","apis-json-modified-info","change-log","cicd-contract-testing","design-async-webhooks","design-compatibility","design-idempotency","design-long-running-operations","design-robustness","design-validation","experience-sla","github-repository","governance","governance-dependency-management","lifecycle-breaking-changes","lifecycle-deprecation","openapi-http-status-codes","openapi-operation-response-2xx","openapi-operation-response-4xx","openapi-operation-response-5xx","openapi-schema-constraints","openapi-schema-required","operations-error-handling","operations-health-checks","operations-logging","operations-monitoring","operations-rate-limiting","performance","performance-latency","performance-response-time","privacy-policy","problem-details-for-http-apis","road-map","security","security-abuse-prevention","security-authorization","security-input-validation","security-transport","standards","status","status-dashboard","status-history","support","versioning"],"strategies":["api-authorization-is-properly-defined-and-enforced","api-change-is-relative-to-operational-change","api-contracts-are-validated","api-dependencies-are-tracked-and-managed","api-errors-are-standardized-and-informative","api-responses-must-be-meaningful-and-consistent","apis-always-have-well-defined-owners-and-stakeholders","apis-are-aligned-with-industry-using-standards","apis-are-always-high-quality-and-reliable","apis-are-gracefully-deprecated-and-retired","apis-are-made-available-through-a-platform-gateway","apis-are-observable-and-monitored","apis-are-protected-from-abuse-and-misuse","apis-earn-and-maintain-consumer-trust","apis-have-clear-service-level-commitments","apis-must-be-actively-governed","apis-must-be-supported-and-have-feedback-loops","apis-must-reusable-whenever-possible","apis-scale-efficiently-under-load","apis-support-event-driven-and-asynchronous-patterns","breaking-changes-are-prevented-or-carefully-managed","change-is-actively-managed-for-each-api","data-should-be-well-defined-and-validated","operations-must-always-be-secure","operations-must-be-useful-and-consistent","producing-apis-must-be-repeatable"],"author":"Kin Lane"},{"name":"Money","slug":"money","image":"/images/revenue.png","description":"I talk to teams all the time who can't figure out how to make money with their APIs. The business model side of APIs is just as important as the technology, and most organizations haven't done the hard work of connecting their digital resources to actual revenue.","tags":["Solutions"],"properties":["Plans","Pricing"],"policies":["experience-sla","plan-elements","plan-metrics","plan-rate-limits","plan-regions","plan-time-frame","plans"],"strategies":["apis-have-clear-business-models","apis-have-clear-service-level-commitments"],"author":"Kin Lane"},{"name":"Security","slug":"security","image":"/images/security.png","description":"Security is the area where I see the most gap between what teams think they have covered and what's actually happening. The surface area of APIs keeps growing, and most organizations aren't keeping their authentication, authorization, and data protection tight enough.","tags":["Solutions"],"properties":["Authentication","Bounties","OAuthScopes"],"policies":["authentication-jwt","authentication-keys","authentication-oauth","authentication-scopes","design-validation","gateway","governance","openapi-operation-security","openapi-security","openapi-servers","security","security-abuse-prevention","security-authentication","security-authorization","security-cors","security-data-classification","security-input-validation","security-owasp-top-10","security-testing","security-transport","standards"],"strategies":["api-authentication-is-standardized","api-authorization-is-properly-defined-and-enforced","api-data-is-classified-and-protected","api-responses-must-be-meaningful-and-consistent","apis-always-have-well-defined-owners-and-stakeholders","apis-are-aligned-with-industry-using-standards","apis-are-made-available-through-a-platform-gateway","apis-are-protected-from-abuse-and-misuse","apis-earn-and-maintain-consumer-trust","apis-must-be-actively-governed","apis-must-reusable-whenever-possible","data-should-be-well-defined-and-validated","operations-must-always-be-secure","operations-must-be-useful-and-consistent"],"author":"Kin Lane"},{"name":"Simplicity","slug":"simplicity","image":"/images/simplicity.png","description":"I am a big believer that the best APIs are the simple ones. When I see overly complex API designs, I know someone was thinking about their internal architecture instead of the consumer. Keep the surface area small and intuitive.","tags":["Solutions"],"policies":["design-best-practices","design-naming-conventions","design-url-structure","documentation","getting-started","governance","openapi-path-names","plans","standards","support","use-cases"],"strategies":["api-paths-must-conform-to-the-organization","api-responses-must-be-meaningful-and-consistent","apis-are-aligned-with-industry-using-standards","apis-are-always-aligned-with-wider-enterprise","apis-are-always-well-documented","apis-deliver-an-exceptional-developer-experience","apis-follow-consistent-design-patterns","apis-must-be-actively-governed","apis-must-be-supported-and-have-feedback-loops","apis-must-reusable-whenever-possible","data-should-be-well-defined-and-validated","onboarding-is-always-as-easy-as-possible","operations-must-always-be-secure","operations-must-be-useful-and-consistent"],"properties":["Documentation","GettingStarted","SDKs","Examples","Pagination"],"author":"Kin Lane"},{"name":"Workspaces","slug":"workspaces","image":"/images/workspaces.png","description":"Workspaces are one of those building blocks that quietly change everything. Having a dedicated place where teams can collaborate on API design, testing, and operations makes the whole lifecycle more visible and manageable.","tags":["Solutions"],"properties":["GitHubOrganization","GitHubOrganizationEvents","PostmanPublicWorkspace","GitHubRepository","GitHubRepositoryCommitsAtom","GitHubRepositoryreleasesAtom","PostmanWorkspace","Workspaces"],"policies":["github-organization","github-organization-readme","github-organization-repositories","github-organization-teams","github-repository","postman-workspace"],"strategies":["api-development-is-collaborative-across-teams"],"author":"Kin Lane"},{"name":"Trust","slug":"trust","image":"/images/trust.png","description":"Trust is earned at the API level, and I see it broken constantly. When consumers don't trust that your API will be there tomorrow, behave the same way it did yesterday, and protect their data, they won't build anything meaningful on top of it.","tags":["Solutions","Security","Reliability"],"properties":["TermsOfService","PrivacyPolicy","Status","SLA","DeprecationPolicy","BreakingChanges"],"policies":["authentication-jwt","authentication-keys","authentication-oauth","authentication-scopes","cicd-contract-testing","design-compatibility","design-idempotency","experience-sla","governance","governance-compliance-mapping","lifecycle-breaking-changes","lifecycle-deprecation","lifecycle-retirement","openapi-operation-security","openapi-security","operations-monitoring","operations-rate-limiting","privacy-policy","provenance","provenance-certifications","provenance-issues","provenance-pull-requests","provenance-reviews","security-abuse-prevention","security-authentication","security-authorization","security-cors","security-data-classification","security-input-validation","security-owasp-top-10","security-testing","security-transport","status-dashboard","status-history","terms-of-service","versioning-date-base","versioning-semantic-versioning"],"strategies":["api-authentication-is-standardized","api-authorization-is-properly-defined-and-enforced","api-data-is-classified-and-protected","api-provenance-is-maintained-and-auditable","api-versioning-follows-a-defined-standard","apis-are-gracefully-deprecated-and-retired","apis-are-observable-and-monitored","apis-are-protected-from-abuse-and-misuse","apis-earn-and-maintain-consumer-trust","apis-have-clear-service-level-commitments","apis-meet-regulatory-and-compliance-requirements","breaking-changes-are-prevented-or-carefully-managed"],"author":"Kin Lane"},{"name":"Self-Service","slug":"self-service","image":"/images/self-service.png","description":"Self-service is the goal I keep pushing teams toward. If a consumer can't find your API, sign up, get keys, and make their first call without emailing someone, you've created a bottleneck that will kill adoption.","tags":["Solutions","Portals","Documentation"],"properties":["Portals","Documentation","GettingStarted","Sandbox","SDKs","Signup","Console","InteractiveDocumentation"],"policies":["blog-feeds","blogs","cicd-api-mocking","design-hypermedia","documentation-examples","documentation-paths","documentation-request-bodies","documentation-responses","documentation-schema","experience-api-catalog","experience-interactive-documentation","experience-sandbox","getting-started","getting-started-authentication","getting-started-documentation","getting-started-sdks","github-organization","governance","openapi","portals","postman-collection","postman-workspace","sdks","sdks-csharp","sdks-go","sdks-java","sdks-javascript","sdks-php","standards","videos"],"strategies":["api-contracts-are-validated","api-delivery-is-fast-and-design-first","api-paths-must-conform-to-the-organization","api-responses-must-be-meaningful-and-consistent","apis-always-have-well-defined-owners-and-stakeholders","apis-are-aligned-with-industry-using-standards","apis-are-defined-by-technical-contracts","apis-are-discoverable-through-a-central-catalog","apis-are-interoperable-across-systems","apis-are-made-available-through-a-platform-gateway","apis-are-part-of-regular-active-communication","apis-deliver-an-exceptional-developer-experience","apis-must-be-actively-governed","apis-must-reusable-whenever-possible","apis-operations-possess-dedicated-workspaces","apis-work-across-multiple-programming-languages","data-should-be-well-defined-and-validated","onboarding-is-always-as-easy-as-possible","operations-must-always-be-secure","operations-must-be-useful-and-consistent"],"author":"Kin Lane"},{"name":"Compliance","slug":"compliance","image":"/images/compliance.png","description":"Compliance is where the technology, business, and politics of APIs all collide. I see teams struggling to prove their APIs meet regulatory requirements, and without the right governance building blocks in place, it becomes a blocker for operating in any regulated industry.","tags":["Solutions","Legal","Governance"],"properties":["PrivacyPolicy","TermsOfService","DataClassification","AuditLogs"],"policies":["governance-compliance-mapping","operations-logging","privacy-policy","provenance","provenance-certifications","provenance-issues","provenance-pull-requests","provenance-reviews","security-data-classification","security-transport","terms-of-service"],"strategies":["api-authorization-is-properly-defined-and-enforced","api-data-is-classified-and-protected","api-provenance-is-maintained-and-auditable","apis-meet-regulatory-and-compliance-requirements"],"author":"Kin Lane"},{"name":"Performance","slug":"performance","image":"/images/performance.png","description":"Performance is one of those things that's invisible until it isn't. I see teams ignoring latency, throughput, and efficiency until their consumers start complaining, and by then the damage to the experience is already done.","tags":["Solutions","Infrastructure","Operations"],"properties":["Performance","RateLimits","Caching","Pagination","Status"],"policies":["design-batch-operations","experience-sla","operations-caching","operations-pagination","operations-rate-limiting","performance","performance-latency","performance-response-time"],"strategies":["apis-are-observable-and-monitored","apis-are-protected-from-abuse-and-misuse","apis-have-clear-service-level-commitments","apis-scale-efficiently-under-load"],"author":"Kin Lane"},{"name":"Support","slug":"support","image":"/images/support.png","description":"Support is a building block that tells consumers whether you actually care about them using your API. I see teams with no clear channels for getting help, no issue tracking, and no communication about when things will get fixed.","tags":["Solutions","Communication"],"properties":["SupportEmail","SupportGitHubIssues","FeedbackGitHubIssues","FeedbackEmail","Forum","FAQs"],"policies":["feedback","feedback-issues","maintainers","maintainers-email","maintainers-name","questions","questions-issues","support-email","support-issues"],"author":"Kin Lane"},{"name":"Automation","slug":"automation","image":"/images/automation.png","description":"I keep shining a light on automation because it's the only way to scale API operations. When testing, validation, deployment, and governance are all manual, you're just adding human error and slowing everything down.","tags":["Solutions","CI/CD","Governance"],"properties":["GitHubActions","Linting","ContractTesting","MockServer","OperationalValidation","APIValidation"],"policies":["business-contract-validator","cicd-contract-testing","cicd-linting","environments","github-organization","github-organization-readme","github-organization-repositories","github-organization-teams","governance","openapi","performance","postman-collection","postman-workspace","rules","sdks","security-testing","source-of-truth-actions","source-of-truth-issues","source-of-truth-pull-requests","source-of-truth-readme","source-of-truth-teams","standards","status","technical-contract-validator"],"strategies":["api-delivery-is-fast-and-design-first","api-governance-is-automated-in-cicd","api-paths-must-conform-to-the-organization","api-responses-must-be-meaningful-and-consistent","apis-always-have-well-defined-owners-and-stakeholders","apis-are-aligned-with-industry-using-standards","apis-are-always-high-quality-and-reliable","apis-are-defined-by-technical-contracts","apis-are-made-available-through-a-platform-gateway","apis-must-be-actively-governed","apis-must-reusable-whenever-possible","apis-operations-possess-dedicated-workspaces","apis-work-across-multiple-programming-languages","data-should-be-well-defined-and-validated","operations-must-always-be-secure","operations-must-be-useful-and-consistent"],"author":"Kin Lane"},{"name":"Governance","slug":"governance","image":"/images/governance.png","description":"Governance is the word that makes engineers cringe, but I see what happens without it. No consistent review process, no enforcement of standards, and teams duplicating effort everywhere. It doesn't have to be heavy-handed, but it has to exist.","tags":["Solutions","Standards","Process"],"properties":["Policies","ApiRules","OperationalRules","Lifecycle","Vocabulary","Compliance"],"policies":["cicd-linting","governance","governance-api-rules","governance-compliance-mapping","governance-lifecycle","governance-maturity-scoring","governance-operational-rules","governance-policies","governance-policy-exceptions","governance-review-approval","governance-vocabulary","guidance","guidance-business","guidance-people","guidance-policies","guidance-technical","lifecycle-change-management","policies","rules"],"strategies":["api-dependencies-are-tracked-and-managed","api-development-is-collaborative-across-teams","api-governance-is-automated-in-cicd","api-maturity-is-measured-and-improved","api-provenance-is-maintained-and-auditable","apis-meet-regulatory-and-compliance-requirements","breaking-changes-are-prevented-or-carefully-managed"],"author":"Kin Lane"},{"name":"Collaboration","slug":"collaboration","image":"/images/collaboration.png","description":"I see teams producing and consuming APIs in complete silos, with no shared visibility into designs, changes, or decisions. Collaboration isn't just a nice-to-have -- it's a building block that prevents the misalignment and integration failures I see everywhere.","tags":["Solutions","Teams"],"properties":["Teams","GitHubOrganization","GitHubRepository","PostmanPublicWorkspace","Contributing"],"policies":["cicd-api-mocking","design-api-first","github-organization","github-organization-readme","github-organization-repositories","github-organization-teams","github-repository","governance","governance-review-approval","maintainers-email","maintainers-name","postman-workspace","source-of-truth-actions","source-of-truth-issues","source-of-truth-pull-requests","source-of-truth-readme","source-of-truth-teams","teams"],"strategies":["api-delivery-is-fast-and-design-first","api-development-is-collaborative-across-teams"],"author":"Kin Lane"},{"name":"Observability","slug":"observability","image":"/images/observability.png","description":"Observability is about shining a light on what's actually happening with your APIs. Who's consuming them, where are failures happening, and what does performance actually look like? Without this visibility, you're flying blind.","tags":["Solutions","Operations","Monitoring"],"properties":["Status","Performance","Errors","Headers","Logging","Monitoring"],"policies":["governance-dependency-management","operations-health-checks","operations-logging","operations-monitoring","performance","performance-latency","performance-response-time","status-dashboard","status-history"],"strategies":["api-dependencies-are-tracked-and-managed","apis-are-observable-and-monitored"],"author":"Kin Lane"},{"name":"Scalability","slug":"scalability","image":"/images/scalability.png","description":"Scalability isn't just about handling more traffic. I see teams struggle as the number of APIs, consumers, and operational surface area grows. If your processes don't scale alongside your APIs, everything starts to break down.","tags":["Solutions","Infrastructure","Architecture"],"properties":["RateLimits","Plans","Gateway","Pagination","Caching"],"policies":["design-batch-operations","experience-localization","gateway","operations-caching","operations-pagination","operations-rate-limiting","security-abuse-prevention"],"strategies":["apis-are-protected-from-abuse-and-misuse","apis-scale-efficiently-under-load"],"author":"Kin Lane"},{"name":"Stability","slug":"stability","image":"/images/stability.png","description":"Stability is what consumers are really asking for when they evaluate your API. I see breaking changes, outages, and weird behavioral shifts erode trust fast. If people can't depend on your API for critical applications, they'll find another one.","tags":["Solutions","Lifecycle","Versioning"],"properties":["Versioning","DeprecationPolicy","ChangeLog","Status","BreakingChanges"],"policies":["cicd-contract-testing","design-compatibility","design-robustness","experience-migration-guides","governance-dependency-management","lifecycle-breaking-changes","lifecycle-deprecation","openapi-version","versioning-date-base","versioning-semantic-versioning"],"strategies":["api-dependencies-are-tracked-and-managed","api-versioning-follows-a-defined-standard","apis-are-gracefully-deprecated-and-retired","apis-earn-and-maintain-consumer-trust","breaking-changes-are-prevented-or-carefully-managed"],"author":"Kin Lane"},{"name":"Interoperability","slug":"interoperability","image":"/images/interoperability.png","description":"Interoperability is where standards really earn their keep in the API landscape. When every API uses different formats, patterns, and conventions, consumers pay the tax every time they try to integrate multiple APIs or switch providers.","tags":["Solutions","Standards","Design"],"properties":["OpenAPI","JSONSchema","MediaTypes","Hypermedia","Vocabulary"],"policies":["cicd-schema-registry","design-async-webhooks","design-compatibility","design-data-types","design-hypermedia","design-media-types","design-robustness","design-url-structure","experience-localization","openapi-http-methods","openapi-operation-request-bodies-media-types","openapi-path-trailing-slashes","openapi-schema-descriptions","openapi-schema-names","openapi-schema-properties","openapi-schema-property-descriptions","openapi-schema-property-names","openapi-schema-property-shapes","openapi-schema-property-types","openapi-schema-type","operations-error-handling","problem-details-for-http-apis","standards-http","standards-json","standards-json-schema","standards-openapi","standards-spectral","standards-yaml"],"strategies":["api-errors-are-standardized-and-informative","apis-are-interoperable-across-systems","apis-follow-consistent-design-patterns","apis-support-event-driven-and-asynchronous-patterns"],"author":"Kin Lane"},{"name":"Velocity","slug":"velocity","image":"/images/velocity.png","description":"Velocity matters because the business side isn't going to wait around. I see the gap between what the business needs and what API teams can deliver growing wider, and without repeatable processes and the right building blocks, teams just can't move fast enough.","tags":["Solutions","Lifecycle","CI/CD"],"properties":["GitHubActions","MockServer","Sandbox","SDKs","GettingStarted"],"policies":["cicd-api-mocking","design-api-first","experience-sandbox","governance-policy-exceptions"],"strategies":["api-delivery-is-fast-and-design-first","api-governance-is-automated-in-cicd"],"author":"Kin Lane"},{"name":"Developer Experience","slug":"developer-experience","image":"/images/developer-experience.png","description":"Developer experience is the thing I'm most passionate about across the API landscape. Poor docs, missing examples, inconsistent patterns, and no tooling -- these are the things that make developers walk away. The experience is the product.","tags":["Solutions","Documentation","Tooling"],"properties":["Documentation","SDKs","PostmanCollection","Examples","GettingStarted","Guides","Console","InteractiveDocumentation"],"policies":["design-api-first","design-best-practices","design-data-types","design-hypermedia","design-long-running-operations","design-naming-conventions","design-url-structure","documentation-examples","documentation-paths","documentation-request-bodies","documentation-responses","documentation-schema","experience-migration-guides","experience-sandbox","getting-started-authentication","getting-started-documentation","getting-started-sdks","openapi-component-examples","openapi-external-docs","openapi-http-methods","openapi-http-status-codes","openapi-operation-description","openapi-operation-id-conventions","openapi-operation-identifiers","openapi-operation-parameter-descriptions","openapi-operation-parameter-enum","openapi-operation-parameter-in","openapi-operation-parameter-names","openapi-operation-parameter-schema","openapi-operation-parameter-types","openapi-operation-parameters","openapi-operation-request-bodies","openapi-operation-request-bodies-examples","openapi-operation-request-bodies-schema","openapi-operation-response-2xx","openapi-operation-response-4xx","openapi-operation-response-5xx","openapi-operation-summary","openapi-path-names","openapi-servers","operations-error-handling","operations-filtering-sorting","operations-pagination","operations-rate-limiting","problem-details-for-http-apis","sdks-csharp","sdks-go","sdks-java","sdks-javascript","sdks-php"],"strategies":["api-delivery-is-fast-and-design-first","api-errors-are-standardized-and-informative","api-parameters-are-well-defined-and-consistent","apis-are-interoperable-across-systems","apis-deliver-an-exceptional-developer-experience","apis-follow-consistent-design-patterns","apis-scale-efficiently-under-load","apis-support-event-driven-and-asynchronous-patterns"],"author":"Kin Lane"},{"name":"Reusability","slug":"reusability","image":"/images/reusability.png","description":"I watch teams rebuild the same patterns, schemas, and components from scratch over and over again. Reusability is one of the promises of APIs that we still haven't delivered on, and it's where a lot of wasted effort and inconsistency lives.","tags":["Solutions","Components","Schema"],"properties":["OpenAPI","JSONSchema","SchemaRegistry","Vocabulary","Extensions"],"policies":["cicd-schema-registry","openapi-component-examples","openapi-component-headers","openapi-component-parameters","openapi-component-responses","openapi-components"],"strategies":["api-parameters-are-well-defined-and-consistent","apis-are-discoverable-through-a-central-catalog"],"author":"Kin Lane"}]

Capabilities Linter
info

Review

View All Rules

API Learnings

APIs

API Governance

API Solutions

API Discovery

API Building Blocks

API Evangelist LLC

Capabilities Linter
info

API Learnings

APIs

API Governance

API Solutions

API Discovery

API Building Blocks

API Evangelist LLC

Rules Viewer

Capabilities Linterinfo

Capabilities Linter
info