Three Collaborative Design Best Practices to Spruce Up Your API Design Process

The real-world applications for APIs tend to get messy, which is why consistency is the key to building effective APIs. You need to create an effective API program to produce consistent APIs that work well in the real world. But how do you do that? You can do that with a collaborative approach to API design.

Collaborative API design is an approach to building APIs where internal and external stakeholders participate in defining and iterating API design standards. By collaborating with all API stakeholders, teams throughout an organization can develop APIs in a truly unified and consistent way. In honor of spring cleaning, we’re sharing three collaborative design best practices you can use to spruce up your API design process.

1) Get the Right People Involved Early in the Process

APIs are pieces of technology designed by humans to solve human problems. Every API is designed with a specific capability that addresses all or part of a problem. However, an API won’t work well if the designer doesn’t understand the real-world problem the API needs to solve.

If you’re designing an API, you need to make sure you understand what that API needs to do, which means getting the right people involved early in the design process. Different stakeholders, especially potential API consumers, can provide important context around the use of your API, such as:

• How they might use the API
• What data the API should provide
• What API success would look like

Many organizations build APIs for internal use and other APIs for public consumption. For example, a company may develop internal APIs to enable one or more teams to use the knowledge and skills of subject matter experts within the organization. That same company might build an API that developers can use to build third-party applications. Sometimes companies build APIs for a select group of external partners. Design your APIs alongside conversations with API consumers, whoever they are.

You should share API designs with every stakeholder as you work through the design process. Feedback from stakeholders and consumers helps you correctly determine what endpoints and data to include in your API. And incorporating feedback during the design phase ensures that your APIs will meet the needs of consumers and provide value to the business.

With Stoplight, you can share API designs with stakeholders in real-time and keep track of the information you gather about the people your API will impact. You can generate mock servers and interactive documentation for your APIs. You can also incorporate feedback into your API design and then create a new mockup of your API to make sure it works as intended. You can iterate and fine-tune all your APIs before writing any code.

While it’s best to iterate and finalize your API designs before you write a single line of code, you shouldn’t keep API design completely separate from coding workflows.

2) Integrate with Code Workflows

You need to maintain consistency not only throughout the design process but also in the development process. When you keep API design separate from the coding workflow, you run the risk of having disjointed communication among teams and lengthening the time it takes to get your APIs to deployment.

For example, many companies manage hundreds of APIs, old and new. Too often, the API development happens without input from business stakeholders. The independent efforts mean teams have to go through a lot of back-and-forth and often duplicate their work when designing and developing new APIs. The API-in-progress may be available in a Git repository but not accessible to the development team.

To eliminate this slow, “black-box” approach to creating APIs, successful teams integrate design and coding workflows with Stoplight. Applying a collaborative approach to API design and development eliminates the ambiguity and reduces the time it takes to design and develop a new API. Some customers have seen three weeks or more cut to a matter of days. Using a collaborative approach allows you to speed up the design and development process while still maintaining consistency across your APIs.

You can integrate API design with code workflows by collaborating around OpenAPI documents and projects using Git repositories. Stoplight features native Git integration so you can create a central source of truth for all your API designs and documentation in a Git platform like GitHub, GitLab, or Bitbucket. For non-technical collaborators, you can use the OpenAPI specification to visualize API designs so that they can understand the workings of your API without having to know how to code.

Getting the right people involved early in the process and integrating coding workflows help you create consistent and valuable APIs. But you also need to govern all the APIs you create.

3) Incorporate API Governance

Modern businesses build many APIs, often ranging in the dozens or hundreds. Some companies create thousands of APIs. Ensuring consistency in every API requires some governance. And governance involves getting all your API stakeholders on the same page. Governance initiatives won’t work if you can’t get to some form of agreement on different aspects of the API design.

You should begin a governance practice by coming up with informal points of agreement among stakeholders. For example, you might begin by agreeing on little things like error formats, naming conventions, and pagination. For more best practices on governance, check out the first podcast episode on API Intersection.

Once the teams convinced stakeholders to agree on aspects of the API design, they created a style guide that all API teams follow. The company enforces many of those decisions programmatically using Spectral, an open-source linter built-in to the Stoplight platform. Every update made to an API design is automatically validated to ensure it matches the company’s style guide.

More than 1,000 Telus employees use Stoplight, including developers and architects. Despite such a large group of stakeholders, the company has created a successful API governance program. Everyone with a stake in Telus’ API program collaborates using Stoplight, providing feedback during the design phase of every API.

Learn More About Collaborative API Design

The three collaborative API design best practices we’ve highlighted today are only a starting point. Learn more about how Stoplight helps organizations streamline their API programs by reviewing some of our case studies.