API Standardization
API Standardization helps ensure that your API definitions comply with your company’s API style guide. API Hub for Design provides various rules to check the operations, parameters and model definitions for compliance. Inconsistencies can be detected and fixed early in the API design process, before the actual implementations are developed and go live.
In addition to the API Hub for Design API standardization rules, you can create custom rules.
Availability
API Standardization is available for organizations on the Enterprise plan. You can see your organization plan on the Plan tab in the Organization Settings. If you are interested in upgrading to the Enterprise plan, please contact us for details.
AsyncAPI standardization is not supported in API Hub for Design On-Premise.
Organization-level OpenAPI Standardization is available in API Hub for Design On-Premise v. 1.19.2 and later. Earlier versions of API Hub for Design On-Premise include similar API-level Style Validation for OpenAPI.
Enable API Standardization and choose rules to apply
Organization owners can enable and configure API Standardization in the organization settings:
Go to My APIs and click next to the organization name in the sidebar.
– or –
In API Hub for Design On-Premise 1.21 and earlier: click your username and select Settings. Then switch to the My Organizations tab and click next to the organization name.
Switch to the Standardization tab.
Select Enable API Standardization for this Organization.
Select the rules to apply or add your own rules.
You will be able to change the selected rules at any time later.
(Optional.) To prevent organization members from publishing non-compliant APIs, select Require API to pass Standardization to be publishable.
(Optional.) To specify if designers can see Standardization errors in the editor page and validation panel, select Allow Designers to view Standardization errors in the Editor page.
Click Save at the top right.
After you click Save, API Hub for Design will scan your organization’s APIs for compliance with the selected rules. The scan may take some time depending on the number and size of your organization’s API definitions.
After the organization-wide scan is complete, individual APIs will be re-scanned when organization members do the following:
Save an API in the API Hub for Design Editor.
Change the default version of an API.
Create, import or fork an API in the organization.
Create custom rules
View results
Applies to: Organization Owners, Designers, non-member collaborators with the Designer role.
Organization-owned APIs that do not comply with standardization rules are displayed with the and badges in My APIs (or with a red "Standardization failed" badge if you use API Hub for Design On-Premise). You can also use the Standardization filter to find non-compliant APIs.
To view the error list, open an API in the API Hub for Design editor and check the Validation panel at the bottom.
Important
API Standardization scan is performed on save. This is different from the normal syntax validation which is performed dynamically as you make changes in the editor.
Automated standardization
This information applies to API Hub for Design SaaS, API Hub for Design On-Premise 1.26 and later.
You can automate standardization checks and get the error list by using API Hub for Design CLI and Registry API.
Using CLI
API Hub for Design CLI provides the api:validate
command to scan a specific API version:
swaggerhub api:validate OWNER/API_NAME/VERSION - validate a specific version swaggerhub api:validate OWNER/API_NAME - validate the default version
The output is a list of standardization errors and warnings with line numbers:
line severity description 2: CRITICAL 'info.license.name' required -> API license must be present and non-empty string 2: CRITICAL 'info.license.url' required -> API license must be present and non-empty string 4: WARNING Semantic Versioning-Version must be MAJOR.MINOR.PATCH 15: CRITICAL 'delete a user' does not comply with the rule -> Summary should start with upper case and end with a dot
The exit codes are:
0 - no errors or warnings
0 - warnings but no errors
1 - at least one CRITICAL error
2 - generic error (for example, the specified API was not found)
Using Registry API
You can get the error list by sending a GET request to https://api.swaggerhub.com/apis/OWNER/API_NAME/VERSION/standardization
in API Hub for Design SaaS or http(s)://SERVER/v1/apis/OWNER/API_NAME/VERSION/standardization
in API Hub for Design On-Premise 1.26 and later. For example:
curl -H "Authorization: YOUR_API_KEY" https://api.swaggerhub.com/apis/MyOrg/MyApi/1.0.0/standardization
Sample response:
{ "standardization": [ { "line": 2, "description": "'info.license.url' required -> API license must be present and non-empty string", "severity": "CRITICAL" }, { "line": 4, "description": "Semantic Versioning-Version must be MAJOR.MINOR.PATCH", "severity": "WARNING" }, ... ] }
Import and Export of Rules
Spectral file format. You can use this to share rules across different organizations and externally.
Spectral is a free tool that checks your APIs for errors and helps you improve them. It can help you improve your APIs' quality, consistency, and security. It is easy to use and can be integrated into your existing development workflow as a valuable tool for anyone who designs, develops, or tests APIs. API Hub for Design supports some of the Core Functions listed here:
pattern
alphabetical
casing
defined
length
truth
falsey
xor
enumeration
Here is also a list that shows API Hub for Design support for Spectral ruleset properties:
Full support |
|
Partial support |
|
No support |
|
To import the rules:
Go to the Organization settings for the organization you want to import the rules into.
Click the Standardization section.
Click Import Rules, enter a path or URL, or browse to select a file in the Spectral format and Upload the file.
Note
The import files must be in YAML or JSON format and cannot be larger than 15MB.
In the dialog, select options for importing rules:
Sync enabled/disabled to imported rules – This imports all custom rules, enabled and disabled, and all selected system rules.
Enable all imported rules – This imports and enables all disabled custom rules from the source organization and all selected system rules.
Only add rules (do not enable) –This imports all custom rules, without enabling them.
Click Import.
We do not support Custom functions, but we support some Core Functions.
Disable API Standardization
API Standardization is disabled automatically when an organization’s Enterprise plan is canceled.
If you need to disable it manually:
Go to My APIs and click next to the organization name in the sidebar.
– or –
In API Hub for Design On-Premise 1.21 and earlier: click your username and select Settings. Then switch to the My Organizations tab and click next to the organization name.
Switch to the Standardization tab.
Clear the Enable API Standardization for this Organization check box. There is no need to unselect individual rules.
Click Save.
Rules
API Hub for Design includes the following built-in standardization rules. You can also create custom rules.
OpenAPI 2.0 (Swagger 2.0)
AsyncAPI
OpenAPI (All)
operationId must be present and non-empty string
Each operation must have an operationId
. Code generators use operationId
as method names, so use IDs that would be appropriate as method names. For example, GET /pets/{id}
could have operationId: getPetById
. API documentation also uses operationId
to generate permalinks to individual operations.
Note
operationId
values must be unique within an API definition.
↑ Back to the rule list
Operation summary must be present and non-empty string
Operation summary
is a short explanation of what the operation does. Summaries are displayed next to the operation paths in the API docs, and are also used by code generators to produce the method documentation. A summary is an analog of the /** ... */
comments in Java or the <summary>
element in C# XML comments.
↑ Back to the rule list
Summary should start with upper case and end with a dot
Use this rule to ensure that the operation summaries are proper sentences.
# Good summary: Upload user profile image. # Bad summary: upload user profile image
↑ Back to the rule list
Operation description must be present and non-empty string
Use the description
element to explain what this operation does and document any prerequisites and usage specifics. The description can be multiline and use Markdown for rich text representation. Detailed, up-to-date documentation helps developers use your API more effectively.
↑ Back to the rule list
Operation must have a tag and non-empty string
Tags are used to group operations logically into categories, such as Account, Payments, Reports, Search, and so on. Use the tags
element to specify an array of tags for an operation.
API Hub for Design uses tags in a few ways:
API documentation displays the operations grouped by tags, which helps navigate and organize large APIs.
Some code generators use tags to name the source code files and group operations into the same source file. For example, all operations with the
payments
tag may be generated in thePaymentsApi
class file.
Note
Unlike the next rule, this one allows multiple tags per operation.
↑ Back to the rule list
Operation must have one and only one tag
Some code generators use tags to group operations into the same API class file. Using a single tag per operation ensures that the operations will not duplicate across several class files.
# Good paths: /pet: post: summary: Add a new pet to the store. tags: - pet # <----- # Bad paths: /pet: post: summary: Add a new pet to the store. tags: - pet # <----- - store # <-----
↑ Back to the rule list
Operation must have at least one 2xx response
Successful and error responses are an important part of an API definition. A successful response has an HTTP status code in the 2xx range, such as 200 OK or 201 Created. Each operation must have at least one successful response defined. In OpenAPI 3.0 definitions, the '2XX'
keyword can be used to represent all successful responses.
↑ Back to the rule list
Operation must have a default response
The default
response covers possible HTTP response codes that are not defined individually for an operation. It is usually used to represent error responses without listing various 4xx codes individually. That said, it is a good idea to explicitly define any known errors, such as 401 Unauthorized or 404 Not Found.
responses: 200: description: Successful operation 401: description: Unauthorized default: # <------ description: Unexpected error
↑ Back to the rule list
API title must be present and non-empty string
The API title is specified by the info.title
field. It appears at the top of API docs on API Hub for Design. Make sure the API title is descriptive and reflects the API purpose.
info: title: Acme Reports API # <------- version: 1.0.0
↑ Back to the rule list
API description must be present and non-empty string
Use the info.description
field to provide an overview of the API. The description can be multiline and use Markdown for rich text representation. For example, you can include information about authentication, rate limits, pagination, filtering, date and time formats, common error codes, links to additional resources (such as blog posts or external examples), and any other details that would help other developers start using your API.
info: title: Acme Reports API version: 1.0.0 description: >- Use the Acme Reports API to create and schedule a variety of reports from your Acme data. Reports can be daily, weekly, monthly and quarterly. ## Authentication ...
↑ Back to the rule list
API license must be present and non-empty string
The API license lets the potential API consumers know how they are allowed to use your API. Use the info.license
section to specify the license name
and url
. If you want an open-source license, visit https://choosealicense.com and https://opensource.org/licenses to find the most appropriate license for your needs.
info: title: Acme Reports API version: 1.0.0 license: # <------- name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html
↑ Back to the rule list
API contact must be present and non-empty string
This rule requires the info.contact.email
field in API definitions. For public APIs, you can provide the email address of your support or API team. For internal APIs, provide the email of the responsible team or developer.
Note: While this rule requires just info.contact.email
, it is a good idea to also provide info.contact.url
(for example, a link to your support portal or your Slack channel) to give your API consumers multiple options to get in touch.
info: title: Acme Reports API version: 1.0.0 contact: name: Acme Support email: support@example.com # <------- url: https://support.example.com
↑ Back to the rule list
OpenAPI 2.0 (Swagger 2.0)
All model properties must have examples
API Hub for Design uses property examples to display sample requests and responses in the API docs and also to generate mock responses. Use meaningful example values to help your API consumers understand what the actual data will look like.
definitions: User: type: object properties: id: type: integer format: int64 example: 1 # <------- username: type: string example: demo-user # <-------
Note that array properties require that an array-level example should be compliant:
# Good definitions: Product: type: object properties: categories: type: array items: type: string example: # <------- Array example is on the same level as "type: array" - clothes - accessories # Bad - no array-level example (item example is not enough) definitions: Product: type: object properties: categories: type: array items: type: string example: clothes
↑ Back to the rule list
API must not have local definitions (i.e. only $refs are allowed)
To comply with this rule, APIs must not have the definitions
section (even if these local definitions are not used). Instead, schemas should be kept in domains and referenced using domain references.
Good:
responses: 200: description: A single inventory item schema: $ref: 'https://api.swaggerhub.com/domains/acme-org/common-models/1.0#/definitions/InventoryItem'
Bad:
responses: 200: description: A single inventory item schema: $ref: '#/definitions/InventoryItem' definitions: InventoryItem: type: object ...
Note that this rule still allows inline schemas such as
responses: 200: description: An array of strings schema: type: array # <----- items: type: string
↑ Back to the rule list
AsyncAPI
Channel path must not have empty parameter substitution pattern
Channel parameter declarations cannot be empty, e.g., /given/{}
is invalid.
Based on this Spectral rule.
↑ Back to the rule list
Channel path must not include query ("?") or fragment ("#") delimiter
Query parameters and fragments shouldn't be used in channel names. Instead, use bindings to define them.
Based on this Spectral rule.
↑ Back to the rule list
Channel path must not end with slash
Do not include trailing slashes in channel names, as it can cause confusion. Most messaging protocols will treat example/foo
and example/foo/
as different things. Keep in mind that tooling may replace slashes (/) with protocol-specific notation (e.g., . for AMQP), therefore, a trailing slash may result in an invalid channel name in some protocols.
Based on this Spectral rule.
↑ Back to the rule list
Headers schema type must be object
The schema definition of the application headers must be of type “object”.
Based on this Spectral rule.
↑ Back to the rule list
Info description must be present and non-empty string
The AsyncAPI object info description
must be present and non-empty string. Descriptions can contain Markdown so you can implement getting started information like where to find authentication keys, and how to use them.
Based on this Spectral rule.
↑ Back to the rule list
License object must include url
The license
object must specify the URL for the license. Mentioning a license is only useful if people know what the license means, so add a link to the full text for those who need it.
Based on this Spectral rule.
↑ Back to the rule list
Info object must have license object
The info
object must include a license
field.
Based on this Spectral rule.
↑ Back to the rule list
AsyncAPI schema must be latest version (2.5.0)
The schema must be the latest version, currently version 2.5.0.
Based on this Spectral rule.
↑ Back to the rule list
Operation description must be present and non-empty string
Operation objects must have a description.
Based on this Spectral rule.
↑ Back to the rule list
Operation must have operationId
Each operation must have an operationId
. OperationIDs are often used by code generators for methods, functions, etc.
Based on this Spectral rule.
↑ Back to the rule list
Parameter objects must have description
Each parameter
object must include a description
.
Based on this Spectral rule.
↑ Back to the rule list
Server URL must not end with slash
The URL in a server
object cannot end in a slash character. Some tooling doesn't strip trailing slashes off when joining the server.url
to the channels, and you can get awkward URLs like mqtt://example.com/broker//pets
, so it's better to not include a trailing slash.
Based on this Spectral rule.
↑ Back to the rule list
AsyncAPI object must have non-empty servers object
There must be a non-empty servers
object at the root level of an AsyncAPI definition file.
Based on this Spectral rule.
↑ Back to the rule list
Tag object must have description
The tags
object must include a description
field. For example:
tags: - name: "Aardvark" description: Funny-nosed pig-head raccoon. - name: "Badger" description: Angry short-legged omnivores.
Based on this Spectral rule.
↑ Back to the rule list
An AsyncAPI object must have non-empty tags array
The tags
array must be defined. Defining tags allows you to add more information like a description.
Based on this Spectral rule.
↑ Back to the rule list