It’s no secret that API development has taken off in the last few years. In our 2019 State of API industry report, we found that two-thirds of organizations have only started developing APIs in the last five years. As organizations scale their API practice, they are starting to adopt tools to design their APIs in alignment with the OpenAPI specification, formerly referred to as Swagger.
SwaggerHub is a collaboration platform that enables teams to organize and manage their REST APIs while simultaneously scaling and standardizing design practices.
We often get asked by teams who are getting started with the platform,
“What are the best practices my team should employ to get the most out of using SwaggerHub for our API design & documentation?”
These are the 5 top SwaggerHub practices that lead to best-in-class API design:
1. Define and Enforce API Standardization Across Your Organization
In our 2019 State of API report, the number one challenge for teams developing and consuming APIs was “Lack of Standardization”. If the APIs that your team is building and relying upon aren’t designed in a consistent way, they can be harder to interact with and maintain.
In SwaggerHub, it’s easy to automate checks for style guide compliance. You simply select which style rules you want to apply to your organization and right away, you will be able to see which of your APIs need to be updated.
As your team designs new APIs, these style rules will show up in the editor so that every new API is being built in a standardized, consistent way.
If your team is currently conducting manual reviews to ensure design consistency, this style-check automation can save significant time and reduce error. Instead of marking up style errors, those reviews can focus instead on sharing knowledge and best practices.
2. Manage Your API Definitions and Permissions with Organizations, Projects, and Teams
Depending on your company, you could be working on and working with hundreds of different APIs. It’s tough to get a clear sense for who owns what if your organization is only relying upon repositories like GitHub and Bitbucket. By managing your APIs in SwaggerHub, you are establishing a centralized source of truth for all of your APIs and documentation.
Organizations in SwaggerHub offer a simple way to manage group-owned API definitions and the permissions of who can access them. Get started by inviting coworkers to be members and importing your existing APIs. Next, group members into teams, group APIs into projects, and start designing new APIs with the SwaggerHub Editor.
Internally, SmartBear has a company-wide development organization and then organizes teams and projects by each tool that they work on. For example, the engineering team at LoadNinja, a UI performance testing platform by SmartBear, uses SwaggerHub for hosting their internal and external API documentation. SwaggerHub acts as the central source of truth for developers to collaborate on and understand the various internal services of LoadNinja.
3. Create Domains for Common API Components
In our 2019 State of API report, 75% of respondents said that they believe microservice architecture will drive the biggest growth in API adoption in the next two years, a stance only 20% took in 2016. If your team is scaling your API development, chances are that there are common components across your work, like parameters, responses, and data models.
Instead of writing out a 404 error for every API, SwaggerHub domains allow you to follow the Don’t Repeat Yourself (DRY) principle by building out a library of these common components. Simply reference the 404 error schema in your Errors Domain and continue on designing.
That reusability means less manual work for your team and therefore less risk across your projects. It also means as changes are made and the standardized elements evolve, there is only a single location that needs to be updated.
We mentioned earlier that design standardization is the top challenge for teams in 2019. Domains enable your organization to use standard definitions. If the definition of a “customer” or “employee” is consistent across your business, it makes it much easier for end-users to know what to expect when interacting with your APIs.
4. Validate Designs Early with Auto-Mocking
The earlier that your team tests out designs, the easier it is to iterate on them and fix issues. When designers use the SwaggerHub Editor to author and visualize Swagger definitions, they start to validate behavior early with built-in auto-mocking, courtesy of an integration with another SmartBear tool called VirtServer.
This VirtServer Integration automatically creates and maintains a semi-static mock of an API defined in SwaggerHub. This mock is updated every time you save the API, meaning you no longer have to go out of your way to create mock services. Iterate on the design with your team using the preview generated by the VirtServer, all with a couple of clicks.
Auto-mocking provides designers with immediate feedback on their work, but it also impacts how the rest of your software team will work. With the mock in place, developers start developing client applications in parallel instead of waiting for the back end API work to be completed.
5. Incorporating SwaggerHub Into Your CI/CD Pipeline Strategy
Many teams are now looking to build out CI/CD pipelines by integrating their different tools across the full software development lifecycle.
SwaggerHub has native integrations with API management platforms like AWS, Microsoft Azure, IBM API Connect, and Apigee so it is easy to incorporate into your delivery pipeline.
SwaggerHub is most useful when it is the source of truth for an organization’s REST APIs. By syncing your API definitions with source control repositories like GitHub, Bitbucket, and GitLab, you can ensure that there is versioning consistency for both documentation and code across platforms and across your organization. Teams can even push SDKs and code templates to these repository systems, removing a lot of the leg work of building a new service and letting developers focus on logic and functionality first.
You can also set up SwaggerHub Webhooks to create custom workflows. For example, the team behind CrossBrowserTesting.com, a web testing platform by SmartBear, uses SwaggerHub to define its API and manage documentation in one place. With webhooks, they have connected SwaggerHub with a template tool that gets the JSON definition file in real-time and displays it in a uniform way.
Getting Started
If your team is already using SwaggerHub already, feel free to reach out if you have questions about any of these best practices. If you are not already using SwaggerHub, you can get started by creating a free account and importing your existing APIs.