In the wide world of web APIs, the need for governance and shared standards increases as a business seriously considers its data value and platform strategy. But, assembling the right governance approach is quite a balancing act of priorities.

Platform architects must balance a top-down directive and bottom-up developer needs. They must consider how to update legacy data structures. They must implement future-proofed API standards that last. They must enforce style. On top of that, API governance must consider how to meet government regulations and industry-sector standards, such as GDPR for data privacy, PSD2 for open banking, or FIHR in healthcare.

Thankfully, best practices have emerged. With OpenAPI Specification and the surrounding tooling ecosystem, API providers are well-positioned to build a governance approach that works. In our LiveCast, Consumer-Centric API Governance, we brought in experts Alianna Inzana, Smartbear, and Kin Lane, Postman, to discuss how to build and enforce fair platform-wide API policies that accelerate business objectives.

API Governance Starts With The Human Element

Alianna Inzana, Senior Director, Product Management at SmartBear, brings the human element to simplify API governance.

When you start to consider the rising value of data, how it is exposed becomes a legitimate concern. Unpalatable data lakes, interoperable systems, and smelly code inconsistencies can negatively impact developer experience. APIs, as abstraction layers, can easily inherit these flaws.

According to Alianna Inzana, governance is “an essential part of an API company’s strategy.” API governance is critical for builders of APIs and consumers alike, providing product-minded folks with better leverage and building trust in your brand.

But dictating a single way of thinking can get icky. The phrase “governance” tends to conjure a rigid, conformist image. The idea of a strict mandate from on high feels oppressive, limiting creativity. In short, governance isn’t always embraced joyously by a developer community.

This is why Inzana notes that “human involvement is the start for any API governance journey.” According to Inzana, First comes people, then comes process, then tooling. This process must balance input form two stakeholders: top-down requirements and bottom-up developer user input.

5 Elements For Simple Governance

Alianna Inzana turns to John Maeda’s 10 Laws of Simplicity as a parable for simple API governance.

Your API governance strategy will mimic your API design practices. So, what makes a good design? Take The Laws of Simplicity. These design principles by John Maeda are relatable to many facets of technology and business. Inzana describes how to apply at least five of them to simplify an API governance strategy:

1. Reduce: First, take inventory of your organization’s resources and value. “Governance journeys often begin with taking stock,” says Inzana. This could mean a thoughtful reduction in waste.
2. Organize: Organization makes a system of many appear fewer. “There is an evolutionary advantage to finding patterns and utilizing them,” notes Inzana. Finding common denominators is a good start, but to drive consistency, API governance requires organization.
3. Time: As request-response oriented layers, APIs hold a special relationship with time. Governance can expand to offer Service Level Agreements (SLAs) that consider uptime.
4. Learn: Learn and implement an API style guide. API contracts provide a standard structure that is machine-readable, but organizations also require a human-readable rule book.
5. Trust: “API governance can build trust within an organization,” notes Inzana. Building a habit of consistency demonstrates what is essential to your organization, pacifying DX hangups, and security worries.

Are your API practices consistent by intention or consistent by accident? Since the goal of API governance is to build a contract between the provider and consumer, API governance really boils down to trust. Even minor inconsistencies, such as some functions not using CamelCase, or methods using differing error-handling styles, create what Inzana calls “code smell.” Code inconsistency breeds a psychological reaction that could negatively impact developer experience and instills distrust in the platform.

Privileging substance over style is good, but ease of use trumps all. To achieve better usability, Inzana recommends calibrating governance to the needs of the people. “If the goal is simplicity… the process has to be around the unification of people.” This process must be collaborative.

Implementing API Governance With Contract Testing

Kin Lane, Chief Evangelist, Postman, sees contract testing as the best path to design-first API governance.

A contract, in the form of an API specification, can be an API’s best friend. A single source of truth. A mighty tool to bind all stakeholders. And perhaps, the API governors’ best ally.

Kin Lane describes the Cambrian explosion of APIs on the market. Since he began covering the API economy in 2010, he’s watched our space rise from hundreds of public APIs to well over 20,000. We’ve also seen standardization around API specification formats. Out of the RAML vs. API Blueprint vs. Swagger debates dawned a general industry-wide acceptance around OpenAPI Specification.

Though the API economy is maturing, Lane notes that still, with some exceptions, most APIs are poorly built. “There’s a disconnect between producers of APIs and the consumers,” says Lane. An investment in governance through a specification-first mindset could help “bring harmony between these two sides of the coin.”

Since OpenAPI has emerged as a standardized specification format for describing APIs, it makes sense to cook a governance strategy that bakes in OpenAPI. As Lane aptly describes, “API design is a gateway drug for API governance… OpenAPI and being design-first opens the door and lays the foundation for API governance.”

In terms of actually implementing a repeatable governance process, Lane recommends collaboration using Postman. As Lane describes, Postman can not only validate APIs, but verify the specification contracts themselves. Contract testing in this way is made easy with Postman Collections.

Using the right tooling, API providers could quickly build out a testing process that provides PASSS or FAIL notices for simple questions like:

• Is valid JSON?
• Is valid JSON schema?
• Is 200 Status?
• Have Body?

These tests could be developed across the board to ensure adherence to naming, design, security, and even regulatory concerns. On regulation, Lane notes how he is building specific Collections open for public reuse. These templates are catering to regulatory benchmarks like FIHR.

Using a tool from SmartBear or Postman for API testing means you could use the same infrastructure to test the API contract and the documentation. With these abilities, you can handle governance and adherence to internal style guides. “People don’t always see this as governance,” says Kin. “But, these are the beginning steps toward governance and toward making a reliable service.”

Final Thoughts: The API Governance Prioritization Matrix

When building API governance, there are many competing priorities. Management needs an iron fist but must appease all stakeholders. You may need to work with old data formats yet abstract them to enable ease of use. The API requires a firm contract, yet your practices must be flexible enough to encompass new use cases.

On that last point, Inzana notes how governance must co-evolve with the industry. For example, asynchronous protocols like AsyncAPI “expand the API governance definition” to encompass other services.

While the human aspect is essential for governance to remain vital, a big part of ensuring business value is the tooling. OpenAPI, now an open industry standard, helps ensure we reach this business value. In terms of actual implementation, As Lane describes, using OpenAPI to both generate documentation and act as a contract is a go-to strategy for design-first governance.

If you’re lost in a governance matrix of competing priorities, consider Inzana’s lasting thoughts: “Align governance with strategy and business goals. Corporate strategy is part of how you define what is important.”