API Design and Governance Problems Are Not Always Technical

APIs are pieces of technology, but the problems developers face when it comes to API design and governance are not always technical. Designing APIs often involves many different people making policy decisions and multiple API teams acting on them.

Designing an API well requires consistency, but how do you get every stakeholder on the same page? This is one of the hardest problems to solve in API design and governance.

Things you can do to help get stakeholders on the same page include:

• Develop the soft skill of empathy
• Find informal points of agreement
• Decide which terms and meanings to use

All three of these topics came up in this API Intersection podcast interview with Matthew Reinbold. In discussing with API architects, we hear the similar stories: organizational change made possible by APIs also requires soft people skills like effective communication and patience. Only after you work through API design and governance problems as a team can you implement some of your decisions with technical tools.

Develop the Skill of Empathy

APIs are tools that developers use to solve a wide range of real-world problems. Every API is designed to perform a specific task, and sometimes it takes multiple APIs to address the problem at hand.

However, an API can’t do its job if the designer doesn’t understand the problem the API is meant to solve. Understanding a problem requires empathy, and empathy begins with a conversation. You can develop your empathy skills by having conversations with stakeholders, getting regular feedback, and setting up iterative cycles. Empathetic conversations and feedback loops are essential components of API design and governance.

You should gather information about the people your API will impact, typically API client developers and their end-users. You should gather this information during the design phase before you start coding.

Once you understand the needs of client developers and end-users, you can determine what endpoints and data to include in your API. Then with a technical tool like Stoplight, you can:

• Design and mock your API
• Get feedback from stakeholders
• Incorporate feedback into the API design
• Create another API mockup
• Try the API design again

Incorporating feedback during the design phase helps ensure that you’re solving API business requirements right from the start.

Find Informal Points of Agreement

Companies that build APIs tend to build many APIs. Some build hundreds, even thousands, of APIs, with all of them at various stages of the API lifecycle.

API governance attempts to bring consistency to the APIs a company builds. Of course, it’s difficult to get all stakeholders to agree when there’s such a huge diversity of solutions available. However, you can coordinate with stakeholders to find informal points of agreement.

Start by creating an informal group of API collaborators. Then through conversation, find points of agreement that you can use to begin a governance practice. The process will help your organization prevent inconsistency and design better APIs.

For example, the development teams at Schneider Electric came to an agreement on a number of API design elements, including letter case, naming conventions, and syntax. When you design an API with a consistent approach to endpoint and field names, consumers of that API can integrate it with applications without having to look into its syntax.

The stakeholders at Schneider Electric found informal points of agreement that allowed the teams to build consistent, easy-to-use APIs. The teams used Spectral, an open-source JSON/YAML Linter, along with Stoplight, to check API designs for the correct case. They didn’t have to implement regular expressions because the most common case choices are built into the Stoplight platform.

With Stoplight, you can document the decisions teams make during the design phase. And with Spectral, you can codify design decisions and enforce them by creating a ruleset or written style guide.

Decide Which Terms and Meanings to Use

Different teams sometimes refer to the same thing in various ways, and many terms have multiple meanings. For example, the term “itinerary” takes on new meanings in different situations. “Travel itinerary,” “plane flight itinerary,” and “car rental itinerary” are all different things despite sharing the same term. So, an API with “itinerary” as an endpoint will return different responses depending on the context.

If you want your APIs to remain consistent, teams need to decide which words and meanings each API design will use. It also helps to avoid using internal lingo in API designs because some users may not be familiar with it. Inconsistency can slow down API development and lead to problems with your APIs down the road.

When Highmark’s API development teams started using Stoplight, they reviewed their previous approach to API design and data, finding about 10 different ways to refer to a member’s last name. The teams set out to redesign all their existing APIs to improve consistency and simplify different processes, like sharing member ID card information. The teams collaborated with stakeholders to standardize how the organization refers to different data attributes, like a member’s first and last name. They also worked with stakeholders to create consistent data models that the company can use across multiple APIs.

Models, also referred to as schemas, describe the structure of the data for API requests and responses. With Stoplight, you can share these descriptions across API designs, a useful capability since you often end up repeating the same structure in the body of every API endpoint request and response. Sharing models helps you design APIs more efficiently. Instead of having to update an element in many places of an API, you can update the element in one place and have that update reflected across the entire API.

API design and governance require that people work together and make decisions that result in consistent API designs. And with Stoplight, internal and external stakeholders can collaborate effectively through a single platform.

Next Steps

• Start collaborating with API stakeholders for free
• Govern your APIs at scale with a central repository
• Implement automatic linting with our open-source tool Spectral
• Start creating design-first APIs with Stoplight