OpenAPI
OpenAPI (formerly known as Swagger) is a specification for building, documenting, and consuming RESTful APIs. It defines a standard, language-agnostic format for describing APIs, enabling both humans and machines to understand the capabilities of a service without accessing its source code, using the following properties.
- Endpoints and Methods - Defines HTTP methods like GET, POST, PUT, and DELETE.
- Parameters and Responses - Specifies query parameters, headers, and response formats.
- Schemas - Provides reusable data models for request and response payloads.
- Security Schemes - Describes authentication methods such as OAuth 2.0 and API Keys.
- Tags and Metadata - Groups related endpoints and adds descriptions for clarity.
While OpenAPI is used in many different aspects of operations it is best known for a handful of common experiences for both API producers and consumers.
- API Design - Define and validate APIs before implementation.
- API Documentation - Generate user-friendly documentation that simplifies adoption.
- API Testing and Mocking - Simulate API behavior during development.
- API Client SDK Generation - Automatically create SDKs for different languages.
- API Automation - Enable DevOps practices like CI/CD with automated tests and deployments.
OpenAPI simplifies API design, documentation, testing, and integration through a standardized and machine-readable format. It improves developer collaboration, speeds up development, and ensures consistent and reliable APIs, making it a cornerstone of the enterprise HTTP API toolbox.
The technical details of any HTTP API should be defined as OpenAPI, then extended and enriched using OpenAPI overlays throughout the API lifecycle. OpenAPI describes the technical details of individual APIs, but when done at scale across the enterprise, it provides an effective blueprint regarding what the enterprise is capable of.
OpenAPI (formerly known as Swagger) is a specification for describing HTTP APIs in a standard, language-agnostic, machine-readable format. Governed by the OpenAPI Initiative under the Linux Foundation, it lets both humans and machines understand what a service can do — its endpoints, parameters, schemas, and security — without ever reading the source code. It is the closest thing the API economy has to a universal contract, and the foundation nearly every other tool in the toolbox builds on.
- Endpoints, methods, and parameters - A precise description of the paths, HTTP verbs, and inputs an API exposes.
- Reusable schemas - Shared data models for request and response payloads, so structure is defined once and referenced everywhere.
- Security schemes - Declares how an API is authenticated, from API keys to OAuth 2.0, right in the contract.
- One contract, many experiences - The same description drives design, documentation, mocking, testing, SDK generation, and CI/CD automation.
- Extensible through Overlays - The base spec stays authoritative while Overlays enrich and specialize it across the lifecycle.
In real API operations OpenAPI is the source of truth. Teams design and validate an API as OpenAPI before a line of implementation ships, then reuse that one document to generate documentation, stand up mocks, run contract tests, produce client SDKs, and wire deployments into CI/CD. Done at scale across an enterprise it becomes a blueprint of everything the organization is capable of — and in the agentic turn it is the surface an AI agent parses to learn an API before it ever makes a call, which is why a valid, published OpenAPI has quietly become the price of admission for machine-readable, agent-ready APIs.
Open source tools that implement this standard
Harvested from this standard's own governing organisation, with the license read from
each repository rather than assumed. The role is what the tool does
to the specification, from the
shared vocabulary
— so an agent holding one of these documents can resolve straight from a goal to a tool.
| Tool |
Role |
License |
What it does |
|
Swagger UI
|
documents |
Apache-2.0
|
The original interactive OpenAPI console — renders a description as browsable documentation with a live "try it" client against... |
|
OpenAPI Generator
|
generates |
Apache-2.0
|
Generates client SDKs, server stubs and documentation from an OpenAPI description across more than fifty languages — the most w... |
|
Redoc
|
documents |
MIT
|
Renders an OpenAPI description as a single-page reference documentation site, with no server-side component. |
|
Scalar
|
documents |
MIT
|
A modern OpenAPI documentation and API client suite — renders a reference site from a description and ships an interactive clie... |
|
oapi-codegen
|
generates |
Apache-2.0
|
Generates idiomatic Go server boilerplate and clients from an OpenAPI description, wiring into the common Go HTTP routers. |
|
openapi-typescript
|
generates |
MIT
|
Generates TypeScript types directly from an OpenAPI description — types only, no client runtime and no generated transport code. |
|
Prism
|
mocks |
Apache-2.0
|
Turns an OpenAPI description into a running mock server that validates requests and returns example or dynamic responses — an A... |
|
Spectral
|
validates |
Apache-2.0
|
The API style-guide linter — validates OpenAPI, AsyncAPI and Arazzo documents against rulesets you write yourself, and emits ma... |
|
Microcks
|
mocks |
Apache-2.0
|
A mocking and contract-testing platform that imports OpenAPI, AsyncAPI, gRPC and Postman artifacts and serves mocks plus confor... |
|
Redocly CLI
|
validates |
MIT
|
The most production-ready way to EXECUTE an Arazzo document today, and the one most teams already have installed. `redocly resp... |
|
vacuum
|
validates |
MIT
|
An extremely fast OpenAPI linter written in Go, Spectral-ruleset compatible, built to lint very large specifications and whole ... |
|
Specmatic
|
tests |
MIT
|
Executes contracts for both testing and mocking, and is the only Arazzo implementation that will span REST and events in a sing... |
All API tooling →
Referenced on the API Evangelist blog
Where this standard shows up across sixteen years of my writing at apievangelist.com — how it fits into API design, governance, and the agentic turn.
Related Rules
Utilizing an example object in the centralized OpenAPI components library helps make examples reusable across API requests and responses
Utilizing an example object in the centralized OpenAPI components library helps make examples reusable across API requests and responses
Utilizing the headers object in the centralized OpenAPI components library helps make headers reusable across API requests and responses
Utilizing the headers object in the centralized OpenAPI components library helps make headers reusable across API requests and responses
Utilizing centralized headers rate limits allows you to reuse headers across all API requests and responses, enabling a more organized approach to handling the transport and rate limits applied con...
Utilizing centralized headers rate limits allows you to reuse headers across all API requests and responses, enabling a more organized approach to handling the transport and rate limits applied con...
Utilizing centralized retry after headers allows you to reuse headers across all API requests and responses, enabling a more organized approach to handling the transport and rate limiting applied c...
Utilizing centralized retry after headers allows you to reuse headers across all API requests and responses, enabling a more organized approach to handling the transport and rate limiting applied c...
Giving parameters with consistent naming helps make it easier for API consumers to understand how they are able to configure their API requests
Giving parameters with consistent naming helps make it easier for API consumers to understand how they are able to configure their API requests
You need a parameters description provides more depth to what a parameter does and will be displayed via documentation, and other tooling used across the API lifecycle
You need a parameters description provides more depth to what a parameter does and will be displayed via documentation, and other tooling used across the API lifecycle
Limiting the length of parameters description forces us to be more concise in how we describe each parameter, while keeping our documentation and other ways descriptions show up in discovery and po...
Keeping parameters enumerator casing consistent across APIs helps reduce confusion by consumers, and can keep aligned with services and applications putting an API to work
Keeping parameters enumerator casing consistent across APIs helps reduce confusion by consumers, and can keep aligned with services and applications putting an API to work
Giving enums for your parameters helps reduce errors and keeps the inputs for your API requests more consistent for consumers
You need a components parameters object allows all parameters used across an API to be centralized, allowing for reuse and easier governance of the parameters used to configure API requests
Parameters must always possess a example to help define the format and shape of the parameter, setting expections with consumers about what needs to be passed in
Parameters must always possess a example to help define the format and shape of the parameter, setting expections with consumers about what needs to be passed in
Giving an in property for parameters gets explicit about whether a parameter is in the path, query, or a header, making it clear to consumers where they can configure their request
Giving an in property for parameters gets explicit about whether a parameter is in the path, query, or a header, making it clear to consumers where they can configure their request
You need a components parameters object allows all parameters used across an API to be centralized, allowing for reuse and easier governance of the parameters used to configure API requests
Giving a simple, intuitive, and consistent names for your parameters helps make it easier for API consumers to understand how they are able to configure their API requests
Giving a simple, intuitive, and consistent names for your parameters helps make it easier for API consumers to understand how they are able to configure their API requests
Giving short and concise names for your parameters helps make it easier for API consumers to understand how they are able to configure their API requests
Providrequiredg an required property for parameters gets explicit about whether a parameter is required the path, query, or a header, making it clear to consumers where they can configure their req...
Providrequiredg an required property for parameters gets explicit about whether a parameter is required the path, query, or a header, makrequiredg it clear to consumers where they can configure the...
Parameters must always possess a schema to help define the format and shape of the parameter, setting expections with consumers about what needs to be passed in
Parameters must always possess a schema to help define the format and shape of the parameter, setting expections with consumers about what needs to be passed in
Parameters that are of an array type should always have the items defined, being explicit about what is continued as part of the array
Parameters that are of an array type should always have the items defined, being explicit about what is continued as part of the array
Parameters must always use a schema reference that utilizes reusable schema that are defined as part of a centralized schema components library
Parameters must always use a schema reference that utilizes reusable schema that are defined as part of a centralized schema components library
Parameters must always have their schema type defined, being precise about what type of data can be inputted and used to configure an API request
Parameters must always have their schema type defined, being precise about what type of data can be inputted and used to configure an API request
Parameters that are of the integer schema type must have their maximum value set, defining the shape of parameter data passed in with a request
Parameters that are of the integer schema type must have their maximum value set, defining the shape of parameter data passed in with a request
Parameters that are of the integer schema type must have their minimum value set, defining the shape of parameter data passed in with a request
Parameters that are of the integer schema type must have their minimum value set, defining the shape of parameter data passed in with a request
Parameters that are of the type string schema type must have their maximum value set, defining the shape of parameter data passed in with a request
Parameters that are of the string schema type must have their maximum value set, defining the shape of parameter data passed in with a request
Parameters that are of the string schema type must have their minimum value set, defining the shape of parameter data passed in with a request
Parameters that are of the string schema type must have their minimum value set, defining the shape of parameter data passed in with a request
Parameters that are of the string schema type must have a pattern set, using a regex to define the shape of parameter data passed in with a request
Parameters that are of the string schema type must have a pattern set, using a regex to define the shape of parameter data passed in with a request
You need a bad request responses in the centralized OpenAPI components library helps make error responses reusable across API requests
You need a bad request responses in the centralized OpenAPI components library helps make error responses reusable across API requests
You need a conflict responses in the centralized OpenAPI components library helps make error responses reusable across API requests
You need a conflict responses in the centralized OpenAPI components library helps make error responses reusable across API requests
Utilizing the responses object in the centralized OpenAPI components library helps make responses reusable across API requests
You need a forbidden responses in the centralized OpenAPI components library helps make error responses reusable across API requests
You need a forbidden responses in the centralized OpenAPI components library helps make error responses reusable across API requests
Utilizing the responses object in the centralized OpenAPI components library helps make responses reusable across API requests
You need a internal server error responses in the centralized OpenAPI components library helps make error responses reusable across API requests
You need a internal server error responses in the centralized OpenAPI components library helps make error responses reusable across API requests
You need a not found error responses in the centralized OpenAPI components library helps make error responses reusable across API requests
You need a not found error responses in the centralized OpenAPI components library helps make error responses reusable across API requests
You need a too many requests error responses in the centralized OpenAPI components library helps make error responses reusable across API requests
You need a too many requests error responses in the centralized OpenAPI components library helps make error responses reusable across API requests
You need a unauthorized error responses in the centralized OpenAPI components library helps make error responses reusable across API requests
You need a unauthorized error responses in the centralized OpenAPI components library helps make error responses reusable across API requests
Utilizing the schema object in the centralized OpenAPI components library helps make schema reusable across API requests and responses
Utilizing the schema object in the centralized OpenAPI components library helps make schema reusable across API requests and responses
You need an external documentation link present in the OpenAPI for an API, makes it easy for API producers or consumers to find their way to the rest of the operations and resources available aroun...
You need an external documentation link present in the OpenAPI for an API, makes it easy for API producers or consumers to find their way to the rest of the operations and resources available aroun...
You need a contact email address associated with the technical contract so that anyone who comes across the API has someone to email and get more information
You need a contact email address associated with the technical contract so that anyone who comes across the API has someone to email and get more information
You need a contact object associated with the technical contract so that anyone who comes across the API has someone to contact and get more information
You need a contact object associated with the technical contract so that anyone who comes across the API has someone to contact and get more information
You need a contact name associated with the technical contract so that anyone who comes across the API knows who to contact
You need a contact name associated with the technical contract so that anyone who comes across the API knows who to contact
You need a contact url associated with the technical contract so that anyone who comes across the API knows where to go to contact someone
You need a contact url associated with the technical contract so that anyone who comes across the API knows where to go to contact someone
You need a detailed description as part of the OpenAPI info object helps describe what a collection of paths and operations does for consumers, giving a short, concise, and relevant couple of parag...
Eval functions MUST not be included in the description of an API, keeping descriptions to just the text that is needed, and relying on the rest of the OpenAPI to describe what is possible.
Eval functions MUST not be included in the description of an API, keeping descriptions to just the text that is needed, and relying on the rest of the OpenAPI to describe what is possible.
You need a detailed description as part of the OpenAPI info object helps describe what a collection of paths and operations does for consumers, giving a short, concise, and relevant couple of parag...
You need a restriction on the length of the API description expressed as the OpenAPI info description helps provide constraints for consumers when adding a description, and keeps portals, landing p...
Script tags MUST not be included in the description of an API, keeping descriptions to just the text that is needed, and relying on the rest of the OpenAPI to describe what is possible.
Script tags MUST not be included in the description of an API, keeping descriptions to just the text that is needed, and relying on the rest of the OpenAPI to describe what is possible.
You need an info object provides much of the metadata needed for the collection of APIs described in an OpenAPI
You need an info object provides much of the metadata needed for the collection of APIs described in an OpenAPI
You need a license associated with an OpenAPI using the info licensing property so that the legal aspects of licensing the API always travel with the technical contract for an API
You need a Create Commons CC BY NC SA license associated with an OpenAPI using the info licensing property so that the legal aspects of licensing the API always travel with the technical contract f...
You need a Create Commons CC BY NC SA license associated with an OpenAPI using the info licensing property so that the legal aspects of licensing the API always travel with the technical contract f...
You need a license identifier associated with an OpenAPI using the info licensing property so that the legal aspects of licensing the API always travel with the technical contract for an API
You need a license identifier associated with an OpenAPI using the info licensing property so that the legal aspects of licensing the API always travel with the technical contract for an API
You need a license associated with an OpenAPI using the info licensing property so that the legal aspects of licensing the API always travel with the technical contract for an API
You need a license name associated with an OpenAPI using the info licensing property so that the legal aspects of licensing the API always travel with the technical contract for an API
You need a license name associated with an OpenAPI using the info licensing property so that the legal aspects of licensing the API always travel with the technical contract for an API
You need a license url associated with an OpenAPI using the info licensing property so that the legal aspects of licensing the API always travel with the technical contract for an API
You need a license url associated with an OpenAPI using the info licensing property so that the legal aspects of licensing the API always travel with the technical contract for an API
You need a terms of service associated with an OpenAPI using the info terms of service property so that the legal aspects of legal side of the API always travel with the technical contract for an API
You need a terms of service associated with an OpenAPI using the info terms of service property so that the legal aspects of legal side of the API always travel with the technical contract for an API
You need a intuitive and helpful title for your API using the OpenAPI info title is the first impression you will make on the consumers of your API
You need a intuitive and helpful title for your API using the OpenAPI info title is the first impression you will make on the consumers of your API
You need a limitation on the length of the title for your API helps provide constraints for teams naming it, but also keep consistent with other APIs from across teams
You need a consistent casing for the title for your API helps provide constraints for teams naming the API, but also keep consistent with other APIs from across teams
You need a consistent casing for the title for your API helps provide constraints for teams naming the API, but also keep consistent with other APIs from across teams
Publishing a version for your OpenAPI technical contract helps you communicate change with consumers using Semantic or date-based versioning published to the info version property
Publishing a version for your OpenAPI technical contract helps you communicate change with consumers using Semantic or date-based versioning published to the info version property
DELETE HTTP methods needs to be available.
DELETE HTTP methods needs to be available.
GET HTTP methods needs to be available.
GET HTTP methods needs to be available.
POST HTTP methods needs to be available.
POST HTTP methods needs to be available.
PUT HTTP methods needs to be available.
PUT HTTP methods needs to be available.
Each API operation needs a security definition referencing the central security scheme express for an OpenAPI
Each API operation needs a security definition referencing the central security scheme express for an OpenAPI
Each API operation needs a security definition referencing the central security scheme express for an OpenAPI referencing apiKeys property.
Each API operation needs a security definition referencing the central security scheme express for an OpenAPI referencing apiKeys property.
You need a paragraph or two description of each API operation helps API consumers understand what is possible with each API request
You need a paragraph or two description of each API operation helps API consumers understand what is possible with each API request
You need a length limitation for each description of each API operation helps apply constraints to how you describe your APIs, while helping drive consistency across APIs when it comes to search, d...
Operation identifiers provide a unique way to identify each individual API, and requiring them to have consistent casing reduces friction when generating SDKs and automating around APIs
Operation identifiers provide a unique way to identify each individual API, and requiring them to have consistent casing reduces friction when generating SDKs and automating around APIs
Operation identifiers provide a unique way to identify each individual API, and requiring them to have consistent casing reduces friction when generating SDKs and automating around APIs
Operation identifiers provide a unique way to identify each individual API, and requiring them to have consistent casing reduces friction when generating SDKs and automating around APIs.
Operation identifiers provide a unique way to identify each individual API, which then used for SDK generation and other automation
Operation identifiers provide a unique way to identify each individual API, which then used for SDK generation and other automation
You need short and intuitive summary for each API operation helps API consumers understand what is possible with each API request
You need short and intuitive summary for each API operation helps API consumers understand what is possible with each API request
Apply length constraints to the operation summary helps keep them consistent for publishing in documentation
Operation summaries should not have a period, keeping the primary summary for each API as consistent as possible for publishing in documentation
Operation summaries should not have a period, keeping the primary summary foreach API as consistent as possible for publishing in documentation.
You need tags applied to each API operations helps organize and group APIs in portals, documentation, search, and other ways in which APIs are made available
You need tags applied to each API operations helps organize and group APIs in portals, documentation, search, and other ways in which APIs are made available
You need tags applied to each API operations helps organize and group APIs in portals, documentation, search, and other ways in which APIs are made available
You need the first letter of each word applied as a tag to API operations helps keep a consistent layout when published via search, documentation, and other ways APIs are made available
You need the first letter of each word applied as a tag to API operations helps keep a consistent layout when published via search, documentation, and other ways APIs are made available
You need all parameters using the central OpenAPI components parameters object helps increase the reusability of parameters across API operations, but it also help standardize parameter across all ...
You need all parameters using the central OpenAPI components parameters object helps increase the reusability of parameters across API operations, but it also help standardize parameter across all ...
There are very few situations where you actually want the acronym API in the path of your API, only when it is a resource.
There are very few situations where you actually want the acronym API in the path of your API, only when it is a resource.
There needs to be a paths property and have paths declared, giving the minimum viable definition for an API.
There needs to be a paths property and have paths declared, giving the minimum viable definition for an API.
Path segments needs to be kebab case and not have different casing that could cause other problems.
The query delimiter should not be included as part of any API path.
The query delimiter should not be included as part of any API path.
The query delimiter should not be included as part of any API path.
It is common to be explicit and consistent about whether or not to have a trailing slack on each API path
It is common to be explicit and consistent about whether or not to have a trailing slack on each API path
Request bodies use the application/json media type to encode the request payload is a common data format
Request bodies use the application/x-www-form-urlencoded media type to encode the request payload is a common data format
POST requests with a request body needs content defined, giving more detail on what is contained within the API request body
POST requests with a request body needs content defined, giving more detail on what is contained within the API request body
PUT requests with a request body needs content defined, giving more detail on what is contained within the API request body
PUT requests with a request body needs content defined, giving more detail on what is contained within the API request body
DELETE HTTP methods should not have a request body, keeping API requests compliant with the HTTP standard
DELETE HTTP methods should not have a request body, keeping API requests compliant with the HTTP standard
It is helpful to provide a description for request bodies, giving a simple explanation of what can be configured as part of the request payload
It is helpful to provide a description for request bodies, giving a simple explanation of what can be configured as part of the request payload
POST, PUT, and PATCH request bodies needs examples, giving one or more examples of what needs to be submitted for different types of requests
POST, PUT, and PATCH request bodies needs examples, giving one or more examples of what needs to be submitted for different types of requests
POST, PUT, and PATCH request bodies needs examples using references to centralized component examples, giving one or more examples of what needs to be submitted for different types of requests
POST, PUT, and PATCH request bodies needs examples using references to centralized component examples, giving one or more examples of what needs to be submitted for different types of requests
GET HTTP methods should not have a request body, keeping API requests compliant with the HTTP standard
GET HTTP methods should not have a request body, keeping API requests compliant with the HTTP standard
POST HTTP methods can have a request body, giving a structured payload for configuring each API request
POST HTTP methods can have a request body, giving a structured payload for configuring each API request
PUT HTTP methods can have a request body, giving a structured payload for configuring each API request
PUT HTTP methods can have a request body, giving a structured payload for configuring each API request
It is important to be explicit about whether or not the request body for an API operation is required or not
It is important to be explicit about whether or not the request body for an API operation is required or not
POST, PUT, and PATCH request bodies needs schema defined, giving more detail on what the structure of the API request body needs to be
POST, PUT, and PATCH request bodies needs schema defined, giving more detail on what the structure of the API request body needs to be
POST, PUT, and PATCH request bodies needs schema reference defined, giving more detail on what the structure of the API request body needs to be
POST, PUT, and PATCH request bodies needs schema reference defined, giving more detail on what the structure of the API request body needs to be
DELETE responses needs a 204 success HTTP status codes, communicating a success created response to consumers
DELETE responses needs a 204 success HTTP status codes, communicating a success created response to consumers
DELETE 400 bad request HTTP status codes have a schema references to standardize the response payload returned for the error response
DELETE 400 bad request HTTP status codes have a schema references to standardize the response payload returned for the error response
DELETE responses needs a 400 not found HTTP status code, communicating nothing was found to consumers
DELETE responses needs a 400 not found HTTP status code, communicating nothing was found to consumers
DELETE 401 unauthorized HTTP status codes have a schema references to standardize the response payload returned for the error response
DELETE 401 unauthorized HTTP status codes have a schema references to standardize the response payload returned for the error response
DELETE responses needs a 401 unauthorized HTTP status code, communicating that consumers do not have access
DELETE responses needs a 401 unauthorized HTTP status code, communicating that consumers do not have access
DELETE 403 forbidden HTTP status codes have a schema references to standardize the response payload returned for the error response
DELETE 403 forbidden HTTP status codes have a schema references to standardize the response payload returned for the error response
DELETE responses needs a 403 forbidden HTTP status code, communicating that consumers are not allowed to access
DELETE responses needs a 403 forbidden HTTP status code, communicating that consumers are not allowed to access
DELETE 404 not found HTTP status codes have a schema references to standardize the response payload returned for the error response
DELETE 404 not found HTTP status codes have a schema references to standardize the response payload returned for the error response
DELETE responses needs a 404 not found HTTP status code, communicating that nothing was found to consumers
DELETE responses needs a 404 not found HTTP status code, communicating that nothing was found to consumers
DELETE 429 too many requests HTTP status codes have a schema references to standardize the response payload returned for the error response
DELETE 429 too many requests HTTP status codes have a schema references to standardize the response payload returned for the error response
DELETE responses needs a 429 too many requests HTTP status code, communicating a consumer has made too may requests
DELETE responses needs a 429 too many requests HTTP status code, communicating a consumer has made too may requests
DELETE 500 internal server error requests HTTP status codes have a schema references to standardize the response payload returned for the error response
DELETE 500 internal server error requests HTTP status codes have a schema references to standardize the response payload returned for the error response
DELETE responses needs a 500 internal server erorr HTTP status code, communicating the API had a problem to consumers
DELETE responses needs a 500 internal server erorr HTTP status code, communicating the API had a problem to consumers
GET 200 success HTTP status codes needs content property that provides the ability to describe the response content
GET 200 success HTTP status codes needs content property that provides the ability to describe the response content
GET 200 success HTTP status codes needs a description, describing what an API consumer can expect as a result
GET 200 success HTTP status codes needs a description, describing what an API consumer can expect as a result
GET 200 success HTTP status codes have a application/json media type, standardizing the response payload returned for a successful response
GET 200 success HTTP status codes have examples to show one or many examples of responses for different types of API requests
GET 200 success HTTP status codes have examples to show one or many examples of responses for different types of API requests
GET 200 success HTTP status codes have example references to show one or many examples of responses for different types of API requests
GET 200 success HTTP status codes have example references to show one or many examples of responses for different types of API requests
GET 200 success HTTP status codes have a application/json media type, standardizing the response payload returned for a successful response
GET 200 success HTTP status codes have a schema to standardize the response payload returned for a successful response
GET 200 success HTTP status codes have a schema to standardize the response payload returned for a successful response
GET 200 success HTTP status codes have a schema references to standardize the response payload returned for a successful response
GET 200 success HTTP status codes have a schema references to standardize the response payload returned for a successful response
GET responses needs a 200 success HTTP status codes, communicating a successful response to consumers
GET responses needs a 200 success HTTP status codes, communicating a successful response to consumers
GET 400 bad request HTTP status codes have a schema references to standardize the response payload returned for the error response
GET 400 bad request HTTP status codes have a schema references to standardize the response payload returned for the error response
GET responses needs a 400 not found HTTP status code, communicating nothing was found to consumers
GET responses needs a 400 not found HTTP status code, communicating nothing was found to consumers
GET 401 unauthorized HTTP status codes have a schema references to standardize the response payload returned for the error response
GET 401 unauthorized HTTP status codes have a schema references to standardize the response payload returned for the error response
GET responses needs a 401 unauthorized HTTP status code, communicating that consumers do not have access
GET responses needs a 401 unauthorized HTTP status code, communicating that consumers do not have access
GET 403 forbidden HTTP status codes have a schema references to standardize the response payload returned for the error response
GET 403 forbidden HTTP status codes have a schema references to standardize the response payload returned for the error response
GET responses needs a 403 forbidden HTTP status code, communicating that consumers are not allowed to access
GET responses needs a 403 forbidden HTTP status code, communicating that consumers are not allowed to access
GET 404 not found HTTP status codes have a schema references to standardize the response payload returned for the error response
GET 404 not found HTTP status codes have a schema references to standardize the response payload returned for the error response
GET responses needs a 404 not found HTTP status code, communicating that nothing was found to consumers
GET responses needs a 404 not found HTTP status code, communicating that nothing was found to consumers
GET 429 too many requests HTTP status codes have a schema references to standardize the response payload returned for the error response
GET 429 too many requests HTTP status codes have a schema references to standardize the response payload returned for the error response
GET responses needs a 429 too many requests HTTP status code, communicating a consumer has made too may requests
GET responses needs a 429 too many requests HTTP status code, communicating a consumer has made too may requests
GET 500 internal server error requests HTTP status codes have a schema references to standardize the response payload returned for the error response
GET 500 internal server error requests HTTP status codes have a schema references to standardize the response payload returned for the error response
GET responses needs a 500 internal server erorr HTTP status code, communicating the API had a problem to consumers
GET responses needs a 500 internal server erorr HTTP status code, communicating the API had a problem to consumers
POST 201 success HTTP status codes needs content property that provides the ability to describe the response content
POST 201 success HTTP status codes needs content property that provides the ability to describe the response content
POST 201 success HTTP status codes needs a description, describing what an API consumer can expect as a result
POST 201 success HTTP status codes needs a description, describing what an API consumer can expect as a result
POST 201 success HTTP status codes have example references to show one or many examples of responses for different types of API requests
POST 201 success HTTP status codes have example references to show one or many examples of responses for different types of API requests
POST 201 success HTTP status codes have a application/json media type, standardizing the response payload returned for a successful response
POST 201 success HTTP status codes have examples to show one or many examples of responses for different types of API requests
POST 201 success HTTP status codes have examples to show one or many examples of responses for different types of API requests
POST 201 success HTTP status codes have a application/json media type, standardizing the response payload returned for a successful response
POST 201 success HTTP status codes have a schema to standardize the response payload returned for a successful response
POST 201 success HTTP status codes have a schema to standardize the response payload returned for a successful response
POST 201 success HTTP status codes have a schema references to standardize the response payload returned for a successful response
POST 201 success HTTP status codes have a schema references to standardize the response payload returned for a successful response
POST responses needs a 201 success HTTP status codes, communicating a success created response to consumers
POST responses needs a 201 success HTTP status codes, communicating a success created response to consumers
POST 400 bad request HTTP status codes have a schema references to standardize the response payload returned for the error response
POST 400 bad request HTTP status codes have a schema references to standardize the response payload returned for the error response
POST responses needs a 400 not found HTTP status code, communicating nothing was found to consumers
POST responses needs a 400 not found HTTP status code, communicating nothing was found to consumers
POST 401 unauthorized HTTP status codes have a schema references to standardize the response payload returned for the error response
POST 401 unauthorized HTTP status codes have a schema references to standardize the response payload returned for the error response
POST responses needs a 401 unauthorized HTTP status code, communicating that consumers do not have access
POST responses needs a 401 unauthorized HTTP status code, communicating that consumers do not have access
POST 403 forbidden HTTP status codes have a schema references to standardize the response payload returned for the error response
POST 403 forbidden HTTP status codes have a schema references to standardize the response payload returned for the error response
POST responses needs a 403 forbidden HTTP status code, communicating that consumers are not allowed to access
POST responses needs a 403 forbidden HTTP status code, communicating that consumers are not allowed to access
POST 404 not found HTTP status codes have a schema references to standardize the response payload returned for the error response
POST 404 not found HTTP status codes have a schema references to standardize the response payload returned for the error response
POST responses needs a 404 not found HTTP status code, communicating that nothing was found to consumers
POST responses needs a 404 not found HTTP status code, communicating that nothing was found to consumers
POST 429 too many requests HTTP status codes have a schema references to standardize the response payload returned for the error response
POST 429 too many requests HTTP status codes have a schema references to standardize the response payload returned for the error response
POST responses needs a 429 too many requests HTTP status code, communicating a consumer has made too may requests
POST responses needs a 429 too many requests HTTP status code, communicating a consumer has made too may requests
POST 500 internal server error requests HTTP status codes have a schema references to standardize the response payload returned for the error response
POST 500 internal server error requests HTTP status codes have a schema references to standardize the response payload returned for the error response
POST responses needs a 500 internal server erorr HTTP status code, communicating the API had a problem to consumers
POST responses needs a 500 internal server erorr HTTP status code, communicating the API had a problem to consumers
PUT responses needs a 204 success HTTP status codes, communicating a success created response to consumers
PUT responses needs a 204 success HTTP status codes, communicating a success created response to consumers
PUT 400 bad request HTTP status codes have a schema references to standardize the response payload returned for the error response
PUT 400 bad request HTTP status codes have a schema references to standardize the response payload returned for the error response
PUT responses needs a 400 not found HTTP status code, communicating nothing was found to consumers
PUT responses needs a 400 not found HTTP status code, communicating nothing was found to consumers
PUT 401 unauthorized HTTP status codes have a schema references to standardize the response payload returned for the error response
PUT 401 unauthorized HTTP status codes have a schema references to standardize the response payload returned for the error response
PUT responses needs a 401 unauthorized HTTP status code, communicating that consumers do not have access
PUT responses needs a 401 unauthorized HTTP status code, communicating that consumers do not have access
PUT 403 forbidden HTTP status codes have a schema references to standardize the response payload returned for the error response
PUT 403 forbidden HTTP status codes have a schema references to standardize the response payload returned for the error response
PUT responses needs a 403 forbidden HTTP status code, communicating that consumers are not allowed to access
PUT responses needs a 403 forbidden HTTP status code, communicating that consumers are not allowed to access
PUT 404 not found HTTP status codes have a schema references to standardize the response payload returned for the error response
PUT 404 not found HTTP status codes have a schema references to standardize the response payload returned for the error response
PUT responses needs a 404 not found HTTP status code, communicating that nothing was found to consumers
PUT responses needs a 404 not found HTTP status code, communicating that nothing was found to consumers
PUT 429 too many requests HTTP status codes have a schema references to standardize the response payload returned for the error response
PUT 429 too many requests HTTP status codes have a schema references to standardize the response payload returned for the error response
PUT responses needs a 429 too many requests HTTP status code, communicating a consumer has made too may requests
PUT responses needs a 429 too many requests HTTP status code, communicating a consumer has made too may requests
PUT 500 internal server error requests HTTP status codes have a schema references to standardize the response payload returned for the error response
PUT 500 internal server error requests HTTP status codes have a schema references to standardize the response payload returned for the error response
PUT responses needs a 500 internal server erorr HTTP status code, communicating the API had a problem to consumers
PUT responses needs a 500 internal server erorr HTTP status code, communicating the API had a problem to consumers
Schema needs descriptions that provide a narrative of what a schema object is for, and how it can be used, leaving examples to demonstrate what can actually be expected
Schema needs descriptions that provide a narrative of what a schema object is for, and how it can be used, leaving examples to demonstrate what can actually be expected
Schema needs a length limit applied, restricting how long schema descriptions can be, helping keep them concise and consistent
Schema names, keeping the naming of them consistent across APIs, standardizing how consumers can use in their applications.
Schema names, keeping the naming of them consistent across APIs, standardizing how consumers can use in their applications.
Schema needs a length limit applied keeping the names of schema consistent across APIs
Schema names are pascal case, keeping the naming of them consistent across APIs, standardizing how consumers can use in their applications
Schema names are pascal case, keeping the naming of them consistent across APIs, standardizing how consumers can use in their applications
Schema integer properties needs a format property with int32 or int64 applied
Schema integer properties needs a format property with int32 or int64 applied
Schema properties that are of the type array must have an items property defined
Schema properties that are of the type array must have an items property defined
Schema properties that are of the type array needs a max items property defined
Schema properties that are of the type array needs a max items property defined
Schema properties that are of the type array needs a min items property defined
Schema properties that are of the type array needs a min items property defined
Schema properties that are of the type number needs a maximum property defined
Schema properties that are of the type number needs a minimum property defined
Schema properties needs descriptions that provide a narrative of the property contains, and how it can be used
Schema properties needs descriptions that provide a narrative of the property contains, and how it can be used
Schema property descriptions needs a length limit applied, applying constraints to writing descriptions, and keeping consistent across APIs
Schema property enumerators are consistent casing, keeping all entries upper snake case, and consistent across all APIs
Schema property enumerators are consistent casing, keeping all entries upper snake case, and consistent across all APIs
Schema property has enumerators, giving consistent values chosen by consumers when making requests
Schema has properties, giving more detail regarding the structure of each schema being applied as part of a request or a response
Schema has properties, giving more detail regarding the structure of each schema being applied as part of a request or a response
Schema property names are camel case, giving consistent casing across all the schema properties used by APIs
Schema property names are camel case, giving consistent casing across all the schema properties used by APIs
Schema property names have a length restriction applied, keeping names consistent, and avoiding being too long
Schema properties that are of the string type have the max length applied defining the shape of the property
Schema properties that are of the string type have the max length applied defining the shape of the property
Schema properties that are of the string type have the min length applied defining the shape of the property
Schema properties that are of the string type have the min length applied defining the shape of the property
Schema needs a required property defined, being explicit about which properties have to be included with the schema when it is used as part of a request or response
Schema needs a required property defined, being explicit about which properties have to be included with the schema when it is used as part of a request or response
Schema needs a type defined, being explicit about type of data a schema describes and can be used to validate, helping standardize the type of data being made available
Schema needs a type defined, being explicit about type of data a schema describes and can be used to validate, helping standardize the type of data being made available
You need components security schemes which possesses an api-key property that allows to configure how API keys are applied to operations.
You need components security schemes which possesses an api-key property that allows to configure how API keys are applied to operations have a in of header set.
You need components security schemes which possesses an api-key property that allows to configure how API keys are applied to operations have a in of header set.
You need components security schemes which possesses an api-key property that allows to configure how API keys are applied to operations.
You need components security schemes which possesses an api-key property that allows to configure how API keys are applied to operations have a name of api_key set.
You need components security schemes which possesses an api-key property that allows to configure how API keys are applied to operations have a name of api_key set.
You need components security schemes which possesses an api-key property that allows to configure how API keys are applied to operations have a type of apiKey set.
You need components security schemes which possesses an api-key property that allows to configure how API keys are applied to operations have a type of apiKey set.
You need components security schemes so that the security definition for an API have been standardized and are able to be applied across APIs
You need components security schemes so that the security definition for an API have been standardized and are able to be applied across APIs
The tags used to organize operations needs to be available in an alphabetical format keeping easy to navigate for consumers.
Tags used as part of an OpenAPI needs descriptions, giving more of a narrative behind what a tag means when it is applied to an API
Tags used as part of an OpenAPI needs descriptions, giving more of a narrative behind what a tag means when it is applied to an API
Tags used as part of an OpenAPI needs names, giving a simple key word or phrase that represents the tag being applied to APIs
Tags used as part of an OpenAPI needs names, giving a simple key word or phrase that represents the tag being applied to APIs
There needs to be a central tags object applied to the OpenAPI, giving central tags that can be applied across all operations within an OpenAPI
There needs to be a central tags object applied to the OpenAPI, giving central tags that can be applied across all operations within an OpenAPI
There needs to be at least one tag applied to an OpenAPI, giving a key word or phrase that can be applied to API operations
The first letter of each word in a tag being applied to APIs needs to be capitalized, keeping the tags being applied across APIs the same look and feel for organizing and publishing to documentation
Publishing a version for your OpenAPI technical contract helps you communicate change with consumers using date-based versioning published to the info version property
The majority of public APIs available on the Web today put the major version of the API as part of the path for each API
The majority of public APIs available on the Web today put the major version of the API as part of the path for each API
Publishing a version for your OpenAPI technical contract helps you communicate change with consumers using Semantic versioning published to the info version property
GET responses needs to include a Cache-Control header to define caching behavior for clients and intermediaries.
GET responses needs to include a Cache-Control header to define caching behavior for clients and intermediaries.
GET responses needs to include an ETag header for cache validation and conditional requests.
GET responses needs to include an ETag header for cache validation and conditional requests.
Operations marked as deprecated must include a Sunset header indicating when the operation will be removed.
Operations marked as deprecated needs to include a Sunset header indicating when the operation will be removed.
Operations marked as deprecated must include migration information in their description.
Operations marked as deprecated needs to include migration information in their description.
4xx and 5xx error responses must use RFC 7807 Problem Details format with type, title, status, and detail fields.
4xx and 5xx error responses should use RFC 7807 Problem Details format with type, title, status, and detail fields.
Collection endpoints should support filtering through query parameters using consistent naming conventions.
Collection endpoints should support sorting through a consistent sort query parameter.
API responses needs to include links for discoverability, enabling clients to navigate related resources using HATEOAS patterns.
API responses must include links for discoverability, enabling clients to navigate related resources using HATEOAS patterns.
Collection endpoints needs to include a limit or page_size query parameter for controlling response size.
Collection endpoints needs to include an offset or cursor query parameter for navigating through results.
Paginated responses needs to include metadata about total count, page size, and navigation links.
APIs that support event-driven patterns should define webhooks using the OpenAPI webhooks object.
OpenAPI definitions must include at least one server object so consumers know where to send requests.
OpenAPI definitions needs to include server objects for consumer reference.
All production server URLs must use HTTPS to ensure encrypted communication between clients and APIs.
Server URLs should use HTTPS to ensure encrypted communication between clients and APIs.
Each server object must include a description identifying the environment it represents.
Each server object needs to include a description identifying the environment it represents.
Production server URLs must not contain localhost or 127.0.0.1 references.
Schema objects should allow additional properties to support forward compatibility and Postel's Law.
Operations that cannot complete synchronously should return 202 Accepted with a Location header for status polling.
202 Accepted responses needs to include a Retry-After header indicating when the client should poll for status.
Date and time properties must use the date-time format specifier which corresponds to ISO 8601 / RFC 3339 formatting.
Date and time properties should use the date-time format specifier which corresponds to ISO 8601 / RFC 3339 formatting.
API paths must use nouns to represent resources, not verbs. Actions needs to be expressed through HTTP methods, not path segments.
API paths should use nouns to represent resources, not verbs. Actions needs to be expressed through HTTP methods, not path segments.
Resource names in paths should use plural nouns to represent collections consistently.
API paths should not exceed a reasonable nesting depth to maintain simplicity and readability.
