Improve API Governance with These Shareable OpenAPI Templates

Matthew Reinbold

January 6, 2022

Organizations are increasingly called on to manage dozens, if not hundreds, of APIs. Increased scale increases the likelihood of design inconsistency among the interfaces created. These inconsistencies decrease the consumers’ developer experience, increase overall support required, and make the output of the entire API ecosystem feel less cohesive.

Big problems like this may feel as though they warrant an equivalent extensive, heavy-handed intervention commonly associated with API governance. However, OpenAPI design templates can provide a lightweight yet powerful approach for aligning API design.

The problem with the minimally viable OpenAPI template

When an API designer begins an API, they may start with a general template like the one seen here:

This bare-bones, “minimally viable” description illustrating basic OpenAPI syntax is better than nothing. However, if an API creator needs to incorporate pagination into their solution, they must track down outside information. This default template does little to align a design with company standards better or encourage exploring alternative expressions.

The Postman Open Technologies team is about improving API practices across industries. Helping folks move beyond syntactic representation to more meaningful, higher-value design conversations is essential to our mission. Rather than require designers to rediscover portions of standard operations in a piecemeal fashion, we wondered, “What if we could produce and support that useful set of illustrative templates?”

From this question, the OpenAPI Governance Template public workspace was born.

Illustrative templates have several benefits

Templates provide gentle nudges to designers. Copy-and-pasting from a trusted source makes applying a uniform approach easier than attempting to rearticulate a common activity, like sorting, from scratch. Providing designers with a suite of thoughtful templates won’t entirely do away with design reviews and architectural conversations. However, templates will help direct energy toward solving the unique business problem provided by the API, and away from introducing variance on non-value-adding API mechanics.

How to use the OpenAPI templates

Currently, the Postman Open Technologies OpenAPI Governance Templates are organized into the following areas:

• Data Formats: Standard expressions for values commonly seen in OpenAPI descriptions, like dates and country codes.
• Information: Articulation for relaying additional information about the API or request to a client.

• Operations: Conveyance for protocol-specific operations, like caching.

• Patterns: Demonstration of how to manifest patterns like filtering and pagination.

For API designers and developers looking for a quick reference on accomplishing a common task, leveraging this workspace is as simple as finding the appropriate OpenAPI template, copying the appropriate syntax to your design, and customizing as needed.

For teams evaluating the trade-offs between different implementation styles, the templates also allow for an apples-to-apples comparison between approaches. For example, there are four different illustrations for how to version an API at the time of this writing. Rather than relying on the results of a Google search to compare samples of differing intent, specification, and aptitude, this workspace provides a uniform set of templates to compare and contrast approaches.

Finally, for API councils, guilds, or centers of excellence, the workspace serves as a storehouse of ingredients for composing your secret sauce. When you’ve identified your organization’s “house style,” you can combine those elements into your own “meta-template”: a one-stop, comprehensive representation of API design. Then, when your teams begin a new design, they aren’t left in the cold to interpret the company’s style guide. Instead, they simply find a style guide-compliant example within the house template and customize accordingly.

Templates play a vital role in API governance

Ultimately, the Postman Open Technologies OpenAPI Governance templates are about much more than a single pagination or filtering affordance. More broadly, these templates can form a compelling tool for improving API consumer developer experience (DX) across a company. Take, for example, templates that include thoughtful examples and more robust descriptions. It takes more effort to remove a specific “format” property in a schema (and thus convey a generic and less helpful “type: string” reference) than just leaving that additional detail. Finally, rather than having developers make up their own, popularizing RFC or ISO standards through templates is an incredible compatibility lift for the organization.

OpenAPI templates are a lightweight yet powerful API governance technique

API governance does not have to be a stereotypical heavyweight process and manual design reviews. OpenAPI templates are lightweight, well-vetted approaches to API design that promote consistent practice and save time. Furthermore, by capturing similar ways of solving the same problem in the same format, the workspace provides teams with an apples-to-apples opportunity to compare and select the right style for them. Finally, when select patterns are combined into a single “house” artifact, templates powerfully supplement a style guide’s “What” with “How” to express in an OpenAPI description.

Going further—get involved

The Postman Open Technologies OpenAPI Governance Templates are off to a great start. But where they go from here is up to you! If there has been a parameter nuance that you’ve struggled to get consistent or a regular pattern you use in your work that you don’t see there, let us know.

Watch the public workspace for updates, comment where you have questions or suggestions for improvements, and fork to your environment to remix as you see fit. Together, we can continue to capture industry practices to better API designers of all stripes!