What a great week at this year’s SmartBear Connect 2020 virtual event. While I didn’t run into to any of you in the halls between sessions, we did exchange a few Slack messages from our lonely home office outposts.
There definitely were some good sessions at the event, and for those API developers out there, you should take a minute to watch the one given by Stephen Mizell, Director of Product Management for API Design. The title of the session is Using SwaggerHub Registry API to Streamline CI/CD Integration. The virtual session consisted of five sections, specifically:
- DevOps, CI/CD and Git workflows
- Problems addressed by SwaggerHub integrations
- Business impact of not addressing these problems
- Possible solution to these problems
- Demo of SwaggerHub workflow
In the first section, we step back to examine what DevOps is, how Continuous Integration and Continuous Delivery (CI/CD) applies to it, and what the intersection of these two areas are with Git. And, for that matter, with other source control management tools.
So, what is DevOps? The industry research firm Gartner defines DevOps as “a change in IT culture, focusing on rapid IT service delivery through the adoption of agile, lean practices in the context of a system-oriented approach.” Or another way of looking at it “… DevOps emphasizes people (and culture), and it seeks to improve collaboration between operations and development teams.”
Similar to DevOps, the practice of CI/CD embodies both tools and processes used for building, testing, and deploying code. Think of CI/CD as a pipeline that enables application development teams to deliver code changes more frequently and with improved quality.
The last topic covered in this intro revolves around interacting with Git repositories, particularly when it comes to workflows. Today, software development is a collaborative process with developers working in parallel on different parts of the project, using a source code management tool like Git to manage and track changes across multiple workflows.
Common Problems Faced in API Design
The next section of the presentation focuses on some of the problems that organizations face with API development.
As pointed out in the presentation, this can happen when the two processes – API development and API documentation – are disconnected, perhaps being done by two different developers without a tool in the middle to keep them in sync.
- “Our deployed API and documentation are out of sync.”
You may start with an API design, then propose a change, but to use change within the code development process is a manual step. The attempt is to develop according to what they’ve seen rather than use the API design itself to drive development process.
- “We aren’t using our API design to drive development.”
Some organizations take the approach to code first instead of utilizing design first to drive API design and development. The Dev team decides what to do first, then they write code to implement their changes, and from that code they generate the OpenAPI document. The problem, as Stephen points out, is the document doesn’t get published or is published to an uncommon location for API designs or definitions.
- “We are code-first, but aren’t publishing our OpenAPI anywhere.”
This is a common problem that teams face. As changes are made to the API, or new versions are created, it can become difficult to know which API has been pushed to production.
- “We don’t know which version of our API is in production.”
As pointed out in the presentation, these problems arise when API design occurs in one place and the CI/CD-driven software development happens in another.
Potential Business Impacts
The next section of this SwaggerHub presentation deals with the impacts organizations can face when their API design isn’t aligned with the CI/CD pipeline. The first, and probably most obvious issue, deals with API user frustration. When the documentation is incomplete or doesn’t match how the API works, it can frustrate API users, making them hesitant to use the API and potentially erode confidence in the organization. Second, without using API design to drive development, organizations run the risk of developers building something that doesn’t align to the business goals. Third, developers might think they’re on the right track, but ultimately end up building something that doesn’t satisfy the original design. Lastly, when disconnects regarding API design develop around API discoverability. If an OpenAPI document isn’t published to a central place, other teams can’t find it, which may lead to duplication or API inconsistency.
Possible Solutions to the Problem
At this point in the presentation, the topic shifts to a discussion of the ideal, future state that an organization should strive for when integrating their API design with the software development and delivery. Key points in a desired state are:
- API test are automated and leveraging the API design
- Design tools, CI/CD and documentation are aligned and integrated
- Git workflows are the same across tools and services
- The API is validated according to the API design
- Documentation is current with the latest API deployment
SwaggerHub and CI/CD
One way to accelerate your organization to that desired state is to utilize a tool like SwaggerHub as an intermediary with your CI/CD pipeline.
SwaggerHub has built-in integrations for Git (GitHub, GitLab, Bitbucket, as well as most source control management and build tools). As soon as a change occurs with your API, SwaggerHub can push those changes to Git repository.
- Git repositories are integrated with SwaggerHub integrations
As a team works independently, they can create branches directly from SwaggerHub by creating a new version. And all the changes related to that version get pushed to the version-specific branch.
- Every proposed change gets its own branch in the Git repository
SwaggerHub acts as the single source of truth and pushes the API design into the CI/CD pipeline, which can then leverage the same API design.
- Validating an API happens in the CI/CD pipeline
This capability allows developers to automate and improve the efficiency of their CI/CD workflows. It utilizes the Registry API to integrate, search and retrieve, create, and update OpenAPI definitions in the SwaggerHub registry.
- CI/CD uses SwaggerHub Registry API to save, update, publish and mark default
SwaggerHub Demo and Its Ability to Streamline CI/CD Pipeline
At this point in the presentation, we shift from slides to a demo of SwaggerHub to show how it supports your CI/CD pipeline. The demo section begins at 12:36 on the counter where Stephen sets up the demo with an overview of the workflow:
- Proposing an API change within SwaggerHub
- Pushing the change into GitHub
- Recognizing the build fails
- Writing a new piece of code using OpenAPI as a guide
- Creating a pull request and merge into master
- Starting final build, pass test
- Publishing the API document back into SwaggerHub and mark it as default
Jumping into the demo (@14:48), Stephen shows the API he’s created (Book API) using the OpenAPI Spec, and explains how it’s been set up with Git using the SwaggerHub integrations. The demo proceeds according to the workflow described above. Take a few minutes and watch it for yourself. I think you’ll be impressed by the efficiency and automation that SwaggerHub can add to your integration with Git.
Experience SwaggerHub for yourself
If you want to take things a step further, go ahead and download a SwaggerHub free trial. There’s no better way to experience the facility of SwaggerHub with Git than to try it.
If you have questions along the way, check out the SwaggerHub Integrations page. There you’ll find multiple types of integrations supported by SwaggerHub, including a wide array of source control management tools like Git, as well as build tools, API management platforms, and even Webhooks.
So, while you can’t get into the office – yet – you can get into a lot of information on API design, and a lot of interactive videos and training to keep you sharp. Don’t forget there are dozens more videos available to view on-demand at SmartBear Connect 2020.