How to Scale Your API Design Process with OpenAPI

  January 18, 2018

While more and more organizations are embracing design as a critical step in the software development lifecycle, and the lifecycle of their APIs, very few organizations have figured out how to effectively design APIs at scale.

When you’re working within a single team on a confined number of services, design is easier to manage and relying on PDF style guides or wiki pages may be enough to keep everyone aligned. But what happens when that design process needs to scale across multiple teams and hundreds or even thousands of different APIs?

Creating a Design Process that will Actually Scale

We launched SwaggerHub to change the way teams work together to design and document their APIs. Over the last year, we’ve spoken to hundreds of SwaggerHub users to better understand how they’ve been able to scale their design process across multiple teams, and a growing number of APIs.

One user, Cameron Befus, VP Engineering at CrowdFlower, explains his experience of moving from the open source Swagger design tools to SwaggerHub for more scalable API design:

Crowdflower has been using Swagger to define our APIs for some time, and that process has become significantly easier thanks to SwaggerHub. Having great tools like Swagger and SwaggerHub that promote collaboration when designing new services — and makes documenting and integration testing those services much easier — is a huge help to our team.

Scot Hastings, CIO of Bonotel, also shared his experience of launching a new design process for a recent API project:

“As we advanced further into the project, we realized we needed to speed up the process and make it more efficient. We wanted to auto-generate the user interface and facilitate collaboration among our internal and external teams without hassles or communication issues… By giving us the ability to design and develop RESTful APIs faster, we can go to market with new services and service updates sooner,” Hastings says. “That makes SwaggerHub a key cog in our software development lifecycle.”

Organizations like CrowdFlower and Bonotel have been able to scale their API design by standardizing on OpenAPI (Swagger) for API design, and adopting a tool that seamlessly fits into their API workflow and empowers them to more effectively collaborate on their API design in SwaggerHub.

And they also have represented some of the key principles we’ve seen from teams that have successfully scaled their API design process.

Ready to scale your design process? Here are a few important steps you’ll need to take:

1. Align Your Team

Good API design relies on effective coordination between all the stakeholders involved in the API development lifecycle. If your team is not aligned on the design requirements, or if the right people aren’t able to get the necessary visibility into design changes, you will run into friction when you attempt to scale beyond a small set of APIs.

One common way organizations attempt to align team members on the design process is through collaboration tools like Confluence or GitHub. But while these tools have a critical role in the software development lifecycle, they can be complicated to configure for the specific use case of managing your API design workflow.

SwaggerHub was built to help teams stay aligned throughout the entire lifecycle of their APIs. Within SwaggerHub, you can create organizations and invite team members to collaborate on the design and documentation of your APIs. The owner of the organization can assign roles to team members and manage access, based on their involvement in the design process.

Learn more about collaborating in SwaggerHub. 

2. Improve Visibility into the Design Process

Similar to the alignment challenges that teams can face when attempting to scale their API design process, there is also the difficult task of improving visibility across your team. Often we see that teams will start their API design journey with the open source Swagger tools – like Swagger Editor and Swagger UI. And while these tools offer the capabilities needed to effectively model and visualize APIs, they are not built to foster the collaborate requirements of large API teams.

If you’re using OpenAPI to handle your API design, you’ll want to provide a central place for your entire team to access the work that’s being done to design your different services. You’ll also want to ensure that the right people are being notified when changes take place and that you’re not limiting your visibility to disparate emails, Slack messages, and GitHub tickets.

3. Reduce Dependencies

API development can not only be a complicated process, it can also be a slow process for teams involved. Dependencies across teams can be one of the biggest factors slowing down teams that want to move beyond design to start generating code, drafting documentation, and writing test cases. One of the ways that teams that can reduce dependencies enable faster development is through API “mocking” or virtualization.

The API Auto Mocking integration in SwaggerHub creates and maintains a mock of your API using the static responses defined in your spec. You can create a mock automatically when creating a new API in SwaggerHub, or you can create it manually any time later. The mock helps you test your API when designing it, that is, before it is implemented by developers. Also, this integration lets the client application developers start working on their part even before the back end is ready.

Without writing a line of code, you can allow API consumers to develop clients against the mock, which is guaranteed to respond with compatible, realistic payloads. More importantly, you can tune the payloads directly in the OAS Definition by using the “example” construct inside your model definitions.

4. Set and Enforce Design Requirements

A company’s investment in APIs is a long-term endeavor. Design standards don’t just improve implementation of APIs, but also dictate how APIs are updated, or how new APIs are developed. Once design guidelines are set, it’s easier to build off them and allow teams to develop APIs, allowing organizations to scale their design and development process.

Since the design defines how clients and services interact, having differences in designs leads to confusion and overhead during the development phase of your services. These inconsistencies only multiply, and their effects will amplify across the API lifecycle. For example, an API with inconsistent nomenclature in resources may have a different naming style in the controllers during implementation.

One way that SwaggerHub helps address the issue of design consistency is with our built-in Style Validator, to check if your API definition matches certain description standards. For example, your company’s guidelines may require that all the properties have examples specified. Style Validator helps you automate such checks. When creating a Style Validator integration, you specify the checks to perform.

5. Improve Reusability in Design

One of the things we often hear from API teams that are working with the Swagger tooling, and OAS to define their APIs, is that the design process can be extremely tedious when defining multiple endpoints across hundreds of APIs. This is particularly true, when endpoints share a common syntax and have similar definitions, path items, parameters, and responses. The need to repeatedly define every single endpoint separately can slow down the design process, and lead to inconsistencies in API designs.

That’s why SwaggerHub introduced the concept of Domains to the design process. Domains are reusable components that can be shared between multiple APIs and other domains. A domain can contain the following components: definitions, path items, parameters, responses. Users can create and version Domains, and then define the reusable components that can be stored inside them. The components can be referenced from other APIs or Domains, either by the user or the collaborators on the API.

6. Integrate with the Tooling You Trust

Being able to move quickly from design to documenting, building, and deploying the API is critical for establishing a scaling API design process. Even the best design standards won’t help you scale your API design if there is friction when you start to move beyond that initial phase of the API lifecycle.

One of the ways that API vendors have attempted to address this issue is by building additional design capabilities on top of tools, which are more geared toward API management. While it’s great to have one all-in-one solution, it also requires organizations to be locked into a single solution without much flexibility when you want to introduce new tools.

In SwaggerHub, we have taken a different approach — building a world-class API design platform for teams to use as the “source of truth” for their API design process, and then offering seamless integrations to the tools your team trusts to deliver great APIs, including: API gateways like Apigee, AWS, Microsost Azure, or IBM API Connect, source control platforms like Bitbucket, GitHub, and GitLab, and testing tools like SoapUI for functional testing.

Learn more about SwaggerHub API lifecycle integrations. 

Scale Your Design Process

Whether you have an existing design process in-place or are just getting started with a “design first” approach to API development, SwaggerHub can help your team standardize your API design, collaborate across teams, and centralize your API design workflow with OpenAPI/Swagger.

Try SwaggerHub for free! Find out why more than 70,000 API developers, designers, architects, CIOs, and more trust SwaggerHub to help scale their API design process.

Start a trial of SwaggerHub for free right now.

Have questions or want to learn more about how to improve your API design process? Reach out to the SwaggerHub team: [email protected]