API Rules – Guardrails for Good Governance and Best Practices

  April 07, 2020

As your development organization matures and moves toward an API design-first process, you want to ensure that not only do APIs behave as they should, but are also designed for long-term use and adoption over the course of their lives. For this reason, you may decide to create an API style guide – similar to a brand style guide – that dictates how APIs should be designed across an organization. 

An API Style Guide will ensure consistency across all APIs and deliver multiple benefits – accelerating a digital transformation, onboarding engineers to your organization easier, ensuring APIs follow industry guidelines, and providing a positive developer experience for your API consumers – both internal and external.  

How can SwaggerHub Help? 

SwaggerHub is the API designer’s friend when it comes to helping you follow your organization’s style guide. It has embedded rules to check the operations, parameters and model definitions for compliance. You can also use SwaggerHub to build your own internal API standardization guide, allowing you to choose from a list of rules, or add your own. Once the rules are set up and you’re designing the API, SwaggerHub will detect any inconsistencies and provide instant feedback in the editor. So you can fix the problem early in the design process before the actual implementations are developed and the API is reviewed.  

Simplify, Simplify  

It’s easy to use SwaggerHub to set up rules, then enforce them in the API design process. First, the Organization owner will enable Standardization under the Organization setting section of SwaggerHub. They can select some of the predefined rules or create some custom rules.  

Once the rules are enabled, SwaggerHub will scan all the APIs in the Organization and flag any APIs not in compliance with the style guide. You can even filter your APIs to only view ones that aren’t following standardization rules. Inside the editor, SwaggerHub highlights the errors in the API definition files for easy remediation.  

For a more in-depth look at API Standardization, check out this video on Standardizing REST APIs in SwaggerHub.  

Using SwaggerHub To Create Custom Rules  

Industry-specific API rules and style guides are unique, so in effect erect governance guardrails to help enforce compliance. SwaggerHub enables organizations to write their own custom rules for API standardization with their industry-specific style guides. You can validate the OpenAPI definitions for compliance with your API design guidelines.  

For instance, if a style guide requires an API to have a MAJOR.MINOR.PATCH version, we can easily add that to the standardization style guide. In the Create Rule dialog, add the rule name, the path, and regular expression pattern. Set the severity to “Error” if you don’t want the API to be published if it violates that rule. Or, add a custom error message to help the API designer debug it. As you design your rule, the YAML editor will help you verify your rule will capture exactly what you want it to capture. 

Let’s see this in action.

Here are some examples of rules: 

Rule Path Regular Expression
version must be major.minor.patch $.info.version ^([0-9]+)\.([0-9]+)\.([0-9]+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+)?$
must be OpenAPI 3 $.openapi /^3\.\d+\.\d+$/
all operations must have 200 response $.paths.*[put,post,get,delete,patch,options].responses.200 Must Exist
all operations must have 400 response $.paths.*[put,post,get,delete,patch,options].responses.400 Must Exist
all object names MUST use camelCase $..properties.*~ ^[a-z]+[A-Za-z0-9]*[a-z0-9]+$
all attribute names MUST use camelCase $.definitions.*~ ^[a-z]+[A-Za-z0-9]*[a-z0-9]+$
end point URLs must be lowercase $.paths.*~ ^[\/a-z\{\}]+$

Custom rules will continue to grow as organizations explore new ways to utilize this feature, thereby enforcing API governance within their unique industry standards.  

What’s Next 

Adding your style guide enforcement into SwaggerHub editor is only the start. Over the course of the year, look for enhancements to this functionality, such as API and CLI support for rule enforcement, so you can add rules directly into your build pipeline, and a rules library to build and share rules with other API designers.