Three API Collaboration Patterns You Should Follow

It takes many people to build great APIs, especially in a complex organization.

It also requires that teams across your organization collaborate with internal and external stakeholders on defining and iterating API design standards. We call this approach to designing APIs Collaborative API Design, and it ensures that every API you create remains consistent and reliable.

In the spirit of collaboration, let’s highlight three API collaboration patterns you should follow.

1) Collaborate on an API Style Guide

We talk a lot on this blog about using a JSON/YAML Linter to create style guides for your structured data. However, most of the design decisions in a style guide cannot be automated. Many organizations document their design decisions manually, publishing them in a written document. If you want to create consistent APIs across your organization, collaborating on a comprehensive, written style guide will ensure that you do that.

Your style guide should cover far more than basic design decisions. It should include as much information as possible about your API design process. For example, you might include:

• Architectural Style – Let developers know which architectural style to use. Do you want them to use REST, RPC, SOAP, or some other architectural style?
• API Specification – We recommend that you choose a specification to describe your APIs, and OpenAPI is at the top of our list.
• Naming Conventions – Many API teams overlook naming conventions as something they should standardize. Without guidance, you could end up with APIs with a mix of plural nouns, single nouns, and jargon in their endpoints.
• Error Handling – Most organizations handle error codes in the same way. However, to ensure developers follow the same approach to error codes, you should include error handling in your style guide.

You don’t need to include everything in your style guide before you publish it. You should start small and expand your content over time. Your style guide should be a living document that you update over time as your design patterns and styles evolve.

You can find many excellent public API style guides to use as inspiration. Here are a few to check out:

The API Design Guide at Google Cloud APIs

Zalando’s RESTful API and Event Guidelines

The Australian Government’s API Design Standard (beta)

Stoplight wants to make creating and sharing style guides easier. Check out our Shared Style Guides roadmap entry.

2) Plan and Prototype APIs as Early as Possible

Prototyping your APIs early in the design process will prevent a lot of headaches in the long run. If you create an API and it has a critical design flaw, or worse flaws, you’ll spend far less time fixing your API during the design stage than if it’s already coded.

Early prototyping also allows you to work with stakeholders to improve the design and make sure the API works well before you deploy it. Early prototyping generally means you need to mock API calls using a dummy server with manual data or a mock data generator.

Dummy Server with Manual Data

This approach involves using a static response from an existing API and manually editing that response to suit your needs. If you go this route, you need to make sure the text file follows the same structure and fields that the real API does when returning responses. You can use a popular API framework to stage a basic dummy server to return data for your mock API calls. Check out these API frameworks in JavaScript: hapi, Restify, and LoopBack.

This approach allows you to create basic API mocks fairly quickly. However, the data you see returned with the API may become repetitive and outdated.

Mock Data Generator

Instead of manually creating data for your mock API calls, you can use an API description like OpenAPI to generate example responses for your mock API automatically. You can also build a complete mock server using an OpenAPI description file.

Automatically generating data from schemas saves you time and speeds up the prototyping process. You can use an open-source mock server like Prism or a subscription model API design platform like Stoplight.

3) Learn from Other Stakeholders Through Design Reviews

A key aspect of collaborative API design is the participation of all stakeholders in the design process, including reviews. Reviews don’t have to involve every stakeholder, but they should involve multiple stakeholders who can bring new perspectives to the process.

Also, getting feedback from your peers and end-users may inspire you to create API designs you would never have considered. You might discover new uses for your API and ways to improve the design.

You Need to Work Together to Design Consistent APIs

If you want to build a successful API program, you must first design and build consistent APIs. And you can’t do that without effectively collaborating with API stakeholders. And with Stoplight, you can improve collaboration across your entire organization, bringing consistency to all of your APIs.