Every API should have a unique identifier, known as an AID (API Identifier). The APIs.json file, contract, or collection contains its own AID, which the API uses as part of its reference. Additiona...
Every API should have a unique identifier, known as an AID (API Identifier). The APIs.json file, contract, or collection contains its own AID, which the API uses as part of its reference. Additiona...
Each API defined within an APIs.json artifact can specify the base URL for the API. This URL serves as a reference point for developers during onboarding and when making API calls. Additionally, it...
Each API defined within an APIs.json artifact can specify the base URL for the API. This URL serves as a reference point for developers during onboarding and when making API calls. Additionally, it...
The contact object in an APIs.json file allows for referencing the email address of a person or group. This property provides a convenient way for users to seek support for an API, using email as t...
The contact object in an APIs.json file allows for referencing the email address of a person or group. This property provides a convenient way for users to seek support for an API, using email as t...
The contact object in an APIs.json file allows for associating a vCard that represents an individual or organizational entity. It includes common contact information such as a name, email, or other...
The contact object in an APIs.json file includes a full name (FN) property, which specifies the formatted text corresponding to the contact name in the vCard for an API. This provides a quick and c...
The contact object in an APIs.json file includes a full name (FN) property, which specifies the formatted text corresponding to the contact name in the vCard for an API. This provides a quick and c...
The contact object in an APIs.json file allows for associating a vCard that represents an individual or organizational entity. It includes common contact information such as a name, email, or other...
Each API included in an APIs.json file should have a 1-3 paragraph description. This description serves as the first impression for potential consumers and is often displayed in portals, networks, ...
The humanURL property for each API defined in an APIs.json contract provides a link for business or technical consumers to learn more about the API. This URL can direct users to a portal, documenta...
Each API defined within an APIs.json file can include a dedicated image, offering a visual representation of the resource or capability it provides. This enhances the API's approachability and visu...
The APIs property in an APIs.json file enables the definition of one or more APIs as part of a larger collection. Each API within this property has its own subset of metadata, allowing it to be uni...
Each individual API in an APIs.json collection has its own name property, allowing for a clear description of the API. This name might match the API's title in the OpenAPI Info section, but it coul...
This property ensures provides a reference to an about page, either for the company, organization, or government agency behind an API, or specifically about the domain, team, and the APIs they produce
This ensures that an API has had the [APIOps Business Impact Canvas](https://www.apiopscycles.com/resources/business-impact-canvas) applied to the API, requiring that the canvas is present in the r...
This ensures that an API has had the [APIOps Business Model Canvas](https://www.apiopscycles.com/resources/api-business-model-canvas) applied to the API, requiring that the canvas is present in the...
This ensures that an API has had the [APIOps Capacity Canvas](https://www.apiopscycles.com/resources/capacity-canvas) applied to the API, requiring that the canvas is present in the repository and ...
This ensures that an API has had the [APIOps Customer Journey Canvas](https://www.apiopscycles.com/resources/customer-journey-canvas) applied to the API, requiring that the canvas is present in the...
This ensures that an API has had the [APIOps Domain Canvas](https://www.apiopscycles.com/resources/domain-canvas) applied to the API, requiring that the canvas is present in the repository and regi...
This ensures that an API has had the [APIOps Event Canvas](https://www.apiopscycles.com/resources/event-canvas) applied to the API, requiring that the canvas is present in the repository and regist...
This ensures that an API has had the [APIOps Interaction Canvas](https://www.apiopscycles.com/resources/interaction-canvas) applied to the API, requiring that the canvas is present in the repositor...
This ensures that an API has had the [APIOps Locations Canvas](https://www.apiopscycles.com/resources/locations-canvas) applied to the API, requiring that the canvas is present in the repository an...
This ensures that an API has had the [APIOps Locations Canvas](https://www.apiopscycles.com/resources/rest-canvas) applied to the API, requiring that the canvas is present in the repository and reg...
This ensures that an API has had the [APIOps Value Proposition Canvas](https://www.apiopscycles.com/resources/api-value-proposition-canvas) applied to the API, requiring that the canvas is present ...
This property ensures that an API has operational level rules for APIs
This property ensures that there is a link to the validator for the APIs
This property ensures that there is a human readable authentication page available that will provide what type of authentication is used and how it can be applied, as well as any services or toolin...
This property ensures that blogs in support of APIs have an Atom or RSS feed of posts, allowing for the syndication of updates and information around individual APIs and the operations around them
This property ensures that an API has a reference to a blog where anyone can find updates and other stories that will help keep API consumers and other stakeholders up to speed on what is happening...
This property ensures that than an individual API or API operations possesses a change log that catalogs all the changes that have occurred in a recent time frame, with historical and version infor...
This property ensures that an API has the ability to compare two different versions of an API and see what the difference are between them
This property ensures that an API has a deprecation policy shared as part of the contract, communicating what the lifespan of APIs are, each individual version, as well as communication around the ...
This property ensures that there is documentation published for an API, and API consumers will have a set of human-readable instructions for onboarding and integrating with HTTP APIs in their appli...
This property ensures that there is a production environment available for an API, providing base URL, tokens, keys, and other key / value pairs that are needed to integrate with an API
This property ensures that there is a staging environment available for an API, providing base URL, tokens, keys, and other key / value pairs that are needed to integrate with an API
This property ensures that an API has a reference to a examples for individual APIs or as part of common properties, providing examples and synthentic data that can be used for APIs.
This property ensures that there is an email available for API consumers to provide feedback
This property ensures there is a URL to Git issues specifically for providing feedback
This property ensures that there is a link to a discussion forum, providing a way for consumers and producers to engage and support either other throughout the lifecycle
This property ensures that there is a reference to the gateway for an API, referencing where you can manage the configuration for each API
This property ensures that there is a getting started link available, providing a reference for API consumers to get started with an API is as few steps as possible
This property ensures that a GitHub Actions CI/CD pipeline is available for an API, providing a link to the pipeline YAML artifact, which can be used to automate and govern the API as part of the b...
This property ensures that an API is associated with GitHub organization, providing the URL to where you can engage with the operations surrounding an API
This property ensures that an API possess a reference to a dedicated GitHub repository that is used to manage the Open, but also possible server and client code
Each individual API included in an APIs.json file can have a properties collection, which contains specific properties relevant to that API. These properties often start with human-readable element...
This property defines an Insomnia collection available for each API, providing executable artifacts that can be used in the Insomnia client for making calls, and executing automation workflows
This property ensures that an API Commons interface license exists for an API, providing a machine-readable reference for an API, as well as data, backend, and front-end code
This property makes sure there is an API lifecycle schema defining all of the stages of a lifecycle and which policies get applied at each stage of the API lifecycle
This property ensures that an API has a reference to a mock servers for individual APIs or as part of common properties, providing mocked deployments of an API that can be used for making test API ...
This property ensures that there is an OpenAPI present for an API, providing the technical contract that describes the surface area of an API
This property ensures that an OpenAPI has support governance rules, that can be applied during design time via editors, development time via IDE, and run-time via CI/CD pipelines
This property ensures that there is a link to the validator for the OpenAPI technical contract, allowing anyone to see the details of governance being applied
This property ensures that an API has performance testing in place, providing a URL to the performance testing, dashboard, or other resource
This property provides a link to the dedicated plans page that applies to an API, providing information about access tiers, rate limits, and features available for an API as part of a wider API bus...
This property ensures there is a governance policies reference as part of an API contract, usually a common property pointing to a centralized set of policies that get applied
This property ensures there a developer portal associated with an API and that you can find a landing page for the API, documentation, SDKs, and other resources
This property ensures that an API has at least one Postman Collection associated with it, providing automation, tests, and other executable derivatives of an APIs OpenAPI
This property ensures that an API is associated with a Postman Workspace, providing a single location that API producers and/or API consumers can engage around an API
This property provides a link to a pricing page that applies to an API, providing a breakdown of the costs associated with using an API
This property provides a link to the privacy policy for an API, providing the legal details of how privacy is approached for each API
This property ensures that an API has a dedicated link to Git issues for asking questions
This property ensures there is an API rate limits reference associated with API, ensuring the rate limits applied to an API are clearly communicated
This property ensures there is a reference to the road map for an API or for the entire API operations within domain, line of business, or teams
This property ensures that an API has governance rules applied, usually as part of a central set of governance rules, defined by policy, or stages of the API lifecycle
This property ensures that an API has a reference to a sandbox for individual APIs or as part of common properties, providing sandbox, synthetic data, and mock servers for use in making test requests.
This property ensures that there is a Go SDK available for an API, making it easier for Go developers to integrate an API into their applications
This property ensures that there is an SDK available for an API, making it easier for developers to integrate an API into their applications
This property ensures that there is a Java SDK available for an API, making it easier for Java developers to integrate an API into their applications
This property ensures that there is a Node SDK available for an API, making it easier for Node developers to integrate an API into their applications
This property ensures that there is a Python SDK available for an API, making it easier for Python developers to integrate an API into their applications
This property ensures there is a URL to the security page, providing details about how security is handled for an API
This property ensures there is a link to where you sign up for an API, making sure API consumers can access in a single click
This property ensures that there is a status page available for each API, providing the uptime status for any given moment, as well as historical data
This property ensures that an API has email support, providing a valid email address that can be used to get API support
This property ensures that there are Git issues available to support an API, using the issues capability of GitHub, GitLab, or Bitbucket to support API consumers
This property ensures that there is a support page available for an API, providing direct and in-direct support opportunities for each API or for entire API platform
This property ensures that there is a reference to the team behind an API, providing a reference to business and engineering stakeholders
This property ensures that an API has a reference to a terms of service, covering the legal side of using an API
This property ensures that properties of an API or API contract all have valid URLs, checking if any of the URLs are not properly formed, or could be other formats
This property ensures there is a reference to the use cases for an API, helping align an API with the who, what, how, and why of putting an API to work
This property ensures there is a reference to how APIs are versioned, providing a single place where teams can learn about how change is communicated
This property ensures there is a reference to a video page or channel for an API
This property ensures that there is a centralized vocabulary in use for guiding the creation and usage of tags, path segments, and other metadata associated with an APIs
Each API defined in an APIs.json artifact includes a property for adding one or more tags. These tags provide additional context about the resources or capabilities offered by the API, highlighting...
Each API defined in an APIs.json artifact includes a property for adding one or more tags. These tags provide additional context about the resources or capabilities offered by the API, highlighting...
Maintaining consistent casing for tags applied to individual APIs ensures a uniform appearance and enhances search and discovery. Each word in a tag should be capitalized, with the first letter of ...
Maintaining consistent casing for tags applied to individual APIs ensures a uniform appearance and enhances search and discovery. Each word in a tag should be capitalized, with the first letter of ...
An APIs.json artifact can include a set of common properties that describe aspects of API operations shared across multiple APIs in a collection. These common properties are typically managed by a ...
The created property in an APIs.json contract might seem like a minor detail, but it serves an important purpose by providing a timestamp that marks the origin of the intent to offer an interface f...
Every collection of APIs defined in APIs.json should include a one- or two-paragraph description outlining the purpose of the APIs. While individual APIs should have their own descriptions, the col...
APIs.json contracts are often used to power discover and distribute as part of API catalogs and marketplaces. These are places where having a visual representation matching the purpose of a collect...
The maintainers email is to provide a quick way to contact the maintainer of an APIs
The purpose of the FN is to specify the formatted text corresponding to the contact name in the vCard for an APIs
The maintainers property is for identifying the entity who is maintaining an APIs
The modified property in an APIs.json collection indicates the most recent updates made to a group of APIs. While detailed change logs can provide more specifics, an accurate and up-to-date modifie...
The name of a collection of APIs should describe their purpose, target audience, and the problems they aim to solve. While individual APIs should have their own specific names, the name in the APIs...
Every collection of APIs should have a unique identifier. This unique API identifier, or AID, serves as a human and machine-readable reference for organizing and managing various APIs. Similar to a...
The type property in an APIs.json file classifies the business contracts for different types of API collections. It can represent a simple index for a single API, a template or example to showcase ...
The specification version of an APIs.json collection indicates which version of the APIs.json specification is being used. This ensures compatibility and allows for the validation of new properties...
Each collection of APIs defined in an APIs.json artifact includes a property for adding one or more tags. These tags provide additional context about the resources or capabilities offered as part o...
Maintaining consistent casing for tags applied to APIs.json contracts ensures a uniform appearance and enhances search and discovery. Each word in a tag should be capitalized, with the first letter...
Maintaining consistent casing for tags applied to APIs.json contracts ensures a uniform appearance and enhances search and discovery. Each word in a tag should be capitalized, with the first letter...
The top-level URL in an APIs.json file contains a fully qualified link to where the APIs.json file is published. This URL serves as a reference for the API collection and can also be validated. Whe...
AsyncAPI channel parameters should include examples to support mocking, testing, and documentation. Examples help consumers understand expected parameter values for channel subscriptions.
AsyncAPI messages should include examples to support event-driven API mocking, testing, and documentation. Examples help consumers understand message payloads and enable tools to generate realistic...
Each JSON Schema object MUST include a description that explains, in plain language, the purpose and function of the object. This description should provide a clear overview of how the object is in...
Each JSON Schema object MUST include a description that explains, in plain language, the purpose and function of the object. This description should provide a clear overview of how the object is in...
The description for any JSON Schema object should be concise, ensuring it remains easy to read and understand for anyone using or interpreting it. This approach helps keep the schema self-contained...
The description for any JSON Schema object should be concise, ensuring it remains easy to read and understand for anyone using or interpreting it. This approach helps keep the schema self-contained...
Each JSON Schema object MUST have a unique identifier, represented as a URL pointing to its location. The $id property in JSON Schema is used to establish the source of truth for any object being d...
Each JSON Schema object MUST have a unique identifier, represented as a URL pointing to its location. The $id property in JSON Schema is used to establish the source of truth for any object being d...
The $id property in any JSON Schema MUST contain a valid URL pointing to a central registry, repository, or another authoritative source for the object. This URL ensures that the object's source is...
The $id property in any JSON Schema MUST contain a valid URL pointing to a central registry, repository, or another authoritative source for the object. This URL ensures that the object's source is...
Schema integer properties should have a format property with int32 or int64 applied
Schema integer properties should have 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 should have a max items property defined
Schema properties that are of the type array should have a max items property defined
Schema properties that are of the type array should have a min items property defined
Schema properties that are of the type array should have a min items property defined
Schema properties that are of the type number should have a maximum property defined
Schema properties that are of the type number should have a minimum property defined
Schema properties should have descriptions that provide a narrative of the property contains, and how it can be used
Schema properties should have descriptions that provide a narrative of the property contains, and how it can be used
Schema property descriptions should have 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, providing consistent values chosen by consumers when making requests
Schema has properties, providing more detail regarding the structure of each schema being applied as part of a request or a response
Schema has properties, providing more detail regarding the structure of each schema being applied as part of a request or a response
Schema property names are camel case, providing consistent casing across all the schema properties used by APIs
Schema property names are camel case, providing 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
All JSON Schema objects should explicitly define their properties and include at least one required property. Defining required properties enhances the accuracy and reliability of validation for ea...
All JSON Schema objects should explicitly define their properties and include at least one required property. Defining required properties enhances the accuracy and reliability of validation for ea...
The $schema property in a JSON Schema MUST always reference the latest draft of the specification to ensure consistent validation across all objects. Using the most up-to-date version of the specif...
The $schema property in a JSON Schema MUST always reference the latest draft of the specification to ensure consistent validation across all objects. Using the most up-to-date version of the specif...
JSON Schema objects should always include the $schema property to explicitly indicate which version of the specification is being used. This property is essential for tooling and should consistentl...
JSON Schema objects should always include the $schema property to explicitly indicate which version of the specification is being used. This property is essential for tooling and should consistentl...
JSON Schema objects MUST include a title property that describes the object in plain language while reflecting the object's file name. The title should convey the object's content and purpose, prov...
JSON Schema objects MUST include a title property that describes the object in plain language while reflecting the object's file name. The title should convey the object's content and purpose, prov...
The title of JSON Schema objects should be concise yet accurately describe the object's purpose. Keeping the title short ensures clarity and minimizes downstream impact on other items using the obj...
The title of JSON Schema objects should be concise yet accurately describe the object's purpose. Keeping the title short ensures clarity and minimizes downstream impact on other items using the obj...
The name of a JSON Schema object should always be in PascalCase to ensure readability and consistency across APIs. Using PascalCase helps maintain uniformity and aligns the object's name with its p...
The name of a JSON Schema object should always be in PascalCase to ensure readability and consistency across APIs. Using PascalCase helps maintain uniformity and aligns the object's name with its p...
JSON Schema objects should explicitly define their type, ensuring clarity about each object's structure. This allows tools utilizing the schema to accurately validate the object wherever it is appl...
JSON Schema objects should explicitly define their type, ensuring clarity about each object's structure. This allows tools utilizing the schema to accurately validate the object wherever it is appl...
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...
Providing parameters with consistent naming helps make it easier for API consumers to understand how they are able to configure their API requests
Providing parameters with consistent naming helps make it easier for API consumers to understand how they are able to configure their API requests
Having 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
Having 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
Providing enums for your parameters helps reduce errors and keeps the inputs for your API requests more consistent for consumers
Having 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 should 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 should be passed in
Providing 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
Providing 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
Having 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
Providing 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
Providing 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
Providing 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 should 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 should 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
Having a bad request responses in the centralized OpenAPI components library helps make error responses reusable across API requests
Having a bad request responses in the centralized OpenAPI components library helps make error responses reusable across API requests
Having a conflict responses in the centralized OpenAPI components library helps make error responses reusable across API requests
Having 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
Having a forbidden responses in the centralized OpenAPI components library helps make error responses reusable across API requests
Having 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
Having a internal server error responses in the centralized OpenAPI components library helps make error responses reusable across API requests
Having a internal server error responses in the centralized OpenAPI components library helps make error responses reusable across API requests
Having a not found error responses in the centralized OpenAPI components library helps make error responses reusable across API requests
Having a not found error responses in the centralized OpenAPI components library helps make error responses reusable across API requests
Having a too many requests error responses in the centralized OpenAPI components library helps make error responses reusable across API requests
Having a too many requests error responses in the centralized OpenAPI components library helps make error responses reusable across API requests
Having a unauthorized error responses in the centralized OpenAPI components library helps make error responses reusable across API requests
Having 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
Having 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 around ...
Having 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 around ...
HTTP headers should follow Hyphenated-Pascal-Case naming convention for consistency and readability, such as Content-Type, X-Request-Id, or Accept-Language.
Having a contact email address associated with the technical contract ensures that anyone who comes across the API has someone to email and get more information
Having a contact email address associated with the technical contract ensures that anyone who comes across the API has someone to email and get more information
Having a contact object associated with the technical contract ensures that anyone who comes across the API has someone to contact and get more information
Having a contact object associated with the technical contract ensures that anyone who comes across the API has someone to contact and get more information
Having a contact name associated with the technical contract ensures that anyone who comes across the API knows who to contact
Having a contact name associated with the technical contract ensures that anyone who comes across the API knows who to contact
Having a contact url associated with the technical contract ensures that anyone who comes across the API knows where to go to contact someone
Having a contact url associated with the technical contract ensures that anyone who comes across the API knows where to go to contact someone
Having a detailed description as part of the OpenAPI info object helps describe what a collection of paths and operations does for consumers, providing a short, concise, and relevant couple of para...
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.
Having a detailed description as part of the OpenAPI info object helps describe what a collection of paths and operations does for consumers, providing a short, concise, and relevant couple of para...
Having 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 pag...
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.
Having an info object provides much of the metadata needed for the collection of APIs described in an OpenAPI
Having an info object provides much of the metadata needed for the collection of APIs described in an OpenAPI
Having a license associated with an OpenAPI using the info licensing property ensures that the legal aspects of licensing the API always travel with the technical contract for an API
Having a Create Commons CC BY NC SA license associated with an OpenAPI using the info licensing property ensures that the legal aspects of licensing the API always travel with the technical contrac...
Having a Create Commons CC BY NC SA license associated with an OpenAPI using the info licensing property ensures that the legal aspects of licensing the API always travel with the technical contrac...
Having a license identifier associated with an OpenAPI using the info licensing property ensures that the legal aspects of licensing the API always travel with the technical contract for an API
Having a license identifier associated with an OpenAPI using the info licensing property ensures that the legal aspects of licensing the API always travel with the technical contract for an API
Having a license associated with an OpenAPI using the info licensing property ensures that the legal aspects of licensing the API always travel with the technical contract for an API
Having a license name associated with an OpenAPI using the info licensing property ensures that the legal aspects of licensing the API always travel with the technical contract for an API
Having a license name associated with an OpenAPI using the info licensing property ensures that the legal aspects of licensing the API always travel with the technical contract for an API
Having a license url associated with an OpenAPI using the info licensing property ensures that the legal aspects of licensing the API always travel with the technical contract for an API
Having a license url associated with an OpenAPI using the info licensing property ensures that the legal aspects of licensing the API always travel with the technical contract for an API
Having a terms of service associated with an OpenAPI using the info terms of service property ensures that the legal aspects of legal side of the API always travel with the technical contract for a...
Having a terms of service associated with an OpenAPI using the info terms of service property ensures that the legal aspects of legal side of the API always travel with the technical contract for a...
Having 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
Having 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
Having 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
Having 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
Having 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 should be available.
DELETE HTTP methods should be available.
POST HTTP methods should be available.
Each API operation should have a security definition referencing the central security scheme express for an OpenAPI
Each API operation should have a security definition referencing the central security scheme express for an OpenAPI
Each API operation should have a security definition referencing the central security scheme express for an OpenAPI referencing apiKeys property.
Each API operation should have a security definition referencing the central security scheme express for an OpenAPI referencing apiKeys property.
Having a paragraph or two description of each API operation helps API consumers understand what is possible with each API request
Having a paragraph or two description of each API operation helps API consumers understand what is possible with each API request
Having 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, doc...
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
POST operations should not use verbs like retrieve, fetch, get, or read in their summaries. If data retrieval is the goal, a GET method should be used instead to follow RESTful conventions.
Having short and intuitive summary for each API operation helps API consumers understand what is possible with each API request
Having 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.
Having tags applied to each API operations helps organize and group APIs in portals, documentation, search, and other ways in which APIs are made available
Having tags applied to each API operations helps organize and group APIs in portals, documentation, search, and other ways in which APIs are made available
Having tags applied to each API operations helps organize and group APIs in portals, documentation, search, and other ways in which APIs are made available
Having 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
Having 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
Having 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 APIs
Having 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 APIs
Optional parameters should include examples to support API mocking, testing, and documentation. While not strictly required, examples help consumers understand the range of acceptable values.
Required parameters should include examples to support API mocking, testing, and documentation. Examples help consumers understand expected values and enable tools like Microcks to generate realist...
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 must be a paths property and have paths declared, providing the minimum viable definition for an API.
There must be a paths property and have paths declared, providing the minimum viable definition for an API.
Path segments should 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.
RESTful API path segments should not contain action verbs. HTTP methods already convey the action, so verbs in paths indicate a non-RESTful design. Paths should describe resources, not actions.
Path parameters should follow camelCase naming convention for consistency across the API, making parameter names predictable and aligned with common programming conventions.
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 should have content defined, providing more detail on what is contained within the API request body
POST requests with a request body should have content defined, providing more detail on what is contained within the API request body
PUT requests with a request body should have content defined, providing more detail on what is contained within the API request body
PUT requests with a request body should have content defined, providing 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, providing a simple explanation of what can be configured as part of the request payload
It is helpful to provide a description for request bodies, providing a simple explanation of what can be configured as part of the request payload
Request body content should include examples to support API mocking, testing, and documentation. Examples enable tools to generate realistic mock requests and help consumers understand expected pay...
POST, PUT, and PATCH request bodies should have examples, providing one or more examples of what should be submitted for different types of requests
POST, PUT, and PATCH request bodies should have examples, providing one or more examples of what should be submitted for different types of requests
POST, PUT, and PATCH request bodies should have examples using references to centralized component examples, providing one or more examples of what should be submitted for different types of requests
POST, PUT, and PATCH request bodies should have examples using references to centralized component examples, providing one or more examples of what should 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
PATCH operations should use application/merge-patch+json content type as defined in RFC 7396, providing a standardized approach for partial updates to resources.
POST HTTP methods can have a request body, providing a structured payload for configuring each API request
POST HTTP methods can have a request body, providing a structured payload for configuring each API request
PUT HTTP methods can have a request body, providing a structured payload for configuring each API request
PUT HTTP methods can have a request body, providing 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 should have schema defined, providing more detail on what the structure of the API request body should be
POST, PUT, and PATCH request bodies should have schema defined, providing more detail on what the structure of the API request body should be
POST, PUT, and PATCH request bodies should have schema reference defined, providing more detail on what the structure of the API request body should be
POST, PUT, and PATCH request bodies should have schema reference defined, providing more detail on what the structure of the API request body should be
Response content should include examples to support API mocking, testing, and documentation. Examples enable tools to generate realistic mock responses and help consumers understand what to expect.
DELETE responses should have a 204 success HTTP status codes, communicating a success created response to consumers
DELETE responses should have 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 should have a 400 not found HTTP status code, communicating nothing was found to consumers
DELETE responses should have 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 should have a 401 unauthorized HTTP status code, communicating that consumers do not have access
DELETE responses should have 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 should have a 403 forbidden HTTP status code, communicating that consumers are not allowed to access
DELETE responses should have 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 should have a 404 not found HTTP status code, communicating that nothing was found to consumers
DELETE responses should have 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 should have a 429 too many requests HTTP status code, communicating a consumer has made too may requests
DELETE responses should have 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 should have a 500 internal server erorr HTTP status code, communicating the API had a problem to consumers
DELETE responses should have a 500 internal server erorr HTTP status code, communicating the API had a problem to consumers
Error responses (4XX and 5XX) should use application/problem+json media type as defined in RFC 7807, providing a consistent, machine-readable format for conveying error details to API consumers.
Have examples to show one or many examples of responses for different types of API requests
Have examples to show one or many examples of responses for different types of API requests
Have example references to show one or many examples of responses for different types of API requests
Have example references to show one or many examples of responses for different types of API requests
GET 200 success HTTP status codes should have content property that provides the ability to describe the response content
GET 200 success HTTP status codes should have content property that provides the ability to describe the response content
GET 200 success HTTP status codes should have a description, describing what an API consumer can expect as a result
GET 200 success HTTP status codes should have 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 should have a 200 success HTTP status codes, communicating a successful response to consumers
GET responses should have 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 should have a 400 not found HTTP status code, communicating nothing was found to consumers
GET responses should have 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 should have a 401 unauthorized HTTP status code, communicating that consumers do not have access
GET responses should have 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 should have a 403 forbidden HTTP status code, communicating that consumers are not allowed to access
GET responses should have 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 should have a 404 not found HTTP status code, communicating that nothing was found to consumers
GET responses should have 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 should have a 429 too many requests HTTP status code, communicating a consumer has made too may requests
GET responses should have 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 should have a 500 internal server erorr HTTP status code, communicating the API had a problem to consumers
GET responses should have a 500 internal server erorr HTTP status code, communicating the API had a problem to consumers
GET 200 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 should have content property that provides the ability to describe the response content
POST 201 success HTTP status codes should have content property that provides the ability to describe the response content
POST 201 success HTTP status codes should have a description, describing what an API consumer can expect as a result
POST 201 success HTTP status codes should have 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 should have a 201 success HTTP status codes, communicating a success created response to consumers
POST responses should have 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 should have a 400 not found HTTP status code, communicating nothing was found to consumers
POST responses should have 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 should have a 401 unauthorized HTTP status code, communicating that consumers do not have access
POST responses should have 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 should have a 403 forbidden HTTP status code, communicating that consumers are not allowed to access
POST responses should have 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 should have a 404 not found HTTP status code, communicating that nothing was found to consumers
POST responses should have 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 should have a 429 too many requests HTTP status code, communicating a consumer has made too may requests
POST responses should have 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 should have a 500 internal server erorr HTTP status code, communicating the API had a problem to consumers
POST responses should have a 500 internal server erorr HTTP status code, communicating the API had a problem to consumers
PUT responses should have a 204 success HTTP status codes, communicating a success created response to consumers
PUT responses should have 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 should have a 400 not found HTTP status code, communicating nothing was found to consumers
PUT responses should have 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 should have a 401 unauthorized HTTP status code, communicating that consumers do not have access
PUT responses should have 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 should have a 403 forbidden HTTP status code, communicating that consumers are not allowed to access
PUT responses should have 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 should have a 404 not found HTTP status code, communicating that nothing was found to consumers
PUT responses should have 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 should have a 429 too many requests HTTP status code, communicating a consumer has made too may requests
PUT responses should have 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 should have a 500 internal server erorr HTTP status code, communicating the API had a problem to consumers
PUT responses should have a 500 internal server erorr HTTP status code, communicating the API had a problem to consumers
API responses must include the standard rate limit header trio (ratelimit-limit, ratelimit-remaining, ratelimit-reset) to inform consumers of their current usage against rate limits.
Have schemas to show one or many schemas of responses for different types of API requests
Have schemas to show one or many schemas of responses for different types of API requests
Have example references to show one or many schemas of responses for different types of API requests
Have example references to show one or many schemas of responses for different types of API requests
Success responses (2XX excluding 204) should use application/hal+json media type to provide hypermedia links that enable clients to discover related resources and actions, following the HAL specifi...
Schema should have 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 should have 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 should have 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 should have 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 component keys should use snake_case naming convention for consistency, particularly in APIs that follow Python or Ruby conventions.
Schema integer properties should have a format property with int32 or int64 applied
Schema integer properties should have 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 should have a max items property defined
Schema properties that are of the type array should have a max items property defined
Schema properties that are of the type array should have a min items property defined
Schema properties that are of the type array should have a min items property defined
Boolean properties should not use an "is" prefix in their names. The property type already indicates it is a boolean, and the "is" prefix adds unnecessary verbosity.
DateTime properties (format date-time) should include a temporal suffix such as At, Date, Time, or On to clearly communicate that the value represents a point in time.
Schema properties that are of the type number should have a maximum property defined
Schema properties that are of the type number should have a minimum property defined
Schema properties should have descriptions that provide a narrative of the property contains, and how it can be used
Schema properties should have descriptions that provide a narrative of the property contains, and how it can be used
Schema property descriptions should have 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, providing consistent values chosen by consumers when making requests
Schema has properties, providing more detail regarding the structure of each schema being applied as part of a request or a response
Schema has properties, providing more detail regarding the structure of each schema being applied as part of a request or a response
Schema property names are camel case, providing consistent casing across all the schema properties used by APIs
Schema property names are camel case, providing 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
All schema properties must have a type explicitly defined to ensure proper validation, code generation, and documentation. Properties without types are ambiguous and error-prone.
Schema should have 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 should have 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
Required properties should not have default values. If a property is required, the client must provide it explicitly. Having a default on a required property creates confusion about whether the cli...
Schema should have 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 should have 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
Having components security schemes which possesses an api-key property that allows to configure how API keys are applied to operations.
Having 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.
Having 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.
Having components security schemes which possesses an api-key property that allows to configure how API keys are applied to operations.
Having 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.
Having 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.
Having 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.
Having 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.
Having components security schemes ensures that the security definition for an API have been standardized and are able to be applied across APIs
Having components security schemes ensures that the security definition for an API have been standardized and are able to be applied across APIs
The tags used to organize operations should be available in an alphabetical format keeping easy to navigate for consumers.
Tags used as part of an OpenAPI should have descriptions, providing more of a narrative behind what a tag means when it is applied to an API
Tags used as part of an OpenAPI should have descriptions, providing more of a narrative behind what a tag means when it is applied to an API
Tags used as part of an OpenAPI should have names, providing a simple key word or phrase that represents the tag being applied to APIs
Tags used as part of an OpenAPI should have names, providing 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, providing central tags that can be applied across all operations within an OpenAPI
There needs to be a central tags object applied to the OpenAPI, providing central tags that can be applied across all operations within an OpenAPI
There needs to be at least one tag applied to an OpenAPI, providing 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
API versions using date-based format should follow the YYYY-MM-DD pattern, optionally followed by a -preview suffix for pre-release versions.
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
Use random IDs that cannot be guessed. UUIDs are preferred but any other random string will do. Using numeric IDs can lead to enumeration attacks where attackers iterate through possible ID values.
There are many HTTP authorization schemes but some of them are now considered insecure, such as negotiating authentication using specifications like NTLM or OAuth v1.
JSON Web Token implementations must explicitly declare support for RFC8725 to address common pitfalls like ignoring algorithms or using insecure algorithms in JWT validation.
API Keys are passed in headers, cookies or query parameters to access APIs. Those keys can be eavesdropped, especially when they are passed in the URL as logging or history tools will keep track of...
URL parameters MUST NOT contain credentials such as API key, password, or secret. This is a security risk as URLs are often logged and cached.
Basic authentication credentials transported over network are more susceptible to interception than other forms of authentication, and as they are not encrypted it means passwords and tokens are mo...
Read operations (GET, HEAD) should be secured by at least one security scheme to prevent unauthorized access to sensitive data.
All write operations (POST, PUT, PATCH, DELETE) must be secured by at least one security scheme to prevent unauthorized modifications.
By default JSON Schema allows additional properties, which can potentially lead to mass assignment issues, where unspecified fields are passed to the API without validation. Disable them with addit...
Define proper rate limiting to avoid attackers overloading the API. There are many ways to implement rate-limiting, but most of them involve using HTTP headers. All 2XX and 4XX responses should def...
A HTTP 429 response signals the API client is making too many requests, and will supply information about when to retry so that the client can back off calmly without everything breaking. All opera...
Define proper rate limiting to avoid attackers overloading the API. Part of that involves setting a Retry-After header so well-meaning consumers are not polling and potentially exacerbating problems.
Using external resource URLs based on user input for webhooks, file fetching, custom SSO, URL previews, or redirects can lead to Server Side Request Forgery (SSRF) and other security issues.
OWASP API Security recommends defining schemas for all responses, even errors. The 401 describes what happens when a request is unauthorized, so it is important to define this for documentation and...
OWASP API Security recommends defining schemas for all responses, even errors. The 500 describes what happens when a request fails with an internal server error, so it is important to define this f...
Carefully define schemas for all the API responses, including either 400, 422 or 4XX responses which describe errors caused by invalid requests.
Server interactions must not use http:// as it is inherently insecure and can lead to PII and other sensitive information being leaked through traffic sniffing or man-in-the-middle attacks. Use htt...
Servers should use the x-internal vendor extension set to true or false to explicitly declare the intended audience for the API, which will be picked up by most documentation tools.
Make it clear which servers are expected to run in which environment to avoid unexpected problems, exposing test data to the public, or letting bad actors bypass security measures to reach producti...
