In a previous post, we took a look at what an API Design-First process looks like in practice. While there’s technically no need for fancy tooling to get started with API Design-First, making use of modern software development tools can make the process much easier, faster, and more reliable. In this post, we’ll walk through some of the tools you might consider to help you on your API journey.
Ticketing System
As with any other aspect of software development, having a place to create and track tickets is critical. You should treat API design just like any other aspect of the product you’re building. Tickets should be created for putting together the initial designs of APIs as well as defects or updates to the API contracts. They should then flow through your team’s standard workflow, such as “Todo”, “In Progress”, and “Review/QA”, before moving to “Done”. Any type of ticketing system should work, whether it be fully-featured products like Jira or Azure DevOps, or lightweight alternatives like Trello.
XD Handoff
It’s critical that a product or system be used for making XD designs and flows available to API designers. One of our favorite tools for the job is Zeplin, but other tools like Figma and Miro can also be used. Ideally, you want to make it easy to find relevant screens or flows as well as keep track of changes over time so that any updates can be incorporated into the API designs.
Diagramming
By utilizing diagramming tools, you can more easily digitally brainstorm the shape and concepts for an API as well as help to communicate those ideas though things like Request/Response Mappings and comprehensive user flows. While it’s likely that most general-purpose diagramming applications will work, it’s helpful to use ones that are flexible in terms of their workspace size and document formats that can be imported. Lucidchart is one such tool that offers an infinitely expanding canvas as well as effortlessly imports supporting artifacts like XD screen design images. Other tools like Miro and Visio may work as well.
Source Control Management (SCM)
As any developer knows, source code tooling backed by a version control system, like Git, is critical to the productivity and stability of a codebase. By treating your API designs as code, you can obtain many of these same benefits. API designers can create branches where they can make updates to the specs and documentation and then utilize Pull Requests (PRs) to get feedback before making the changes available for everyone to view.
Along with a repository, some sort of Continuous Integration (CI) system is very helpful. The CI will be used to perform automated checks against your specifications, much like unit tests are used for ensuring code quality of applications. Tools like Spectral can be used to lint OpenAPI documents, enforcing consistency, quality, and other API design standards.
Most SCM platforms these days bundle both version control and CI together, which make it easy to get up-and-running. Simply choose the one that you’re most familiar with or has the features you want. Personally, I’ve had great success with both GitHub and Azure DevOps, but I’m sure other platforms like GitLab or Bitbucket will work just as well.
API Specification Authoring
There are several tools that can help make the process of putting together an OpenAPI specification easier. To-date, I’ve yet to find anything that outclasses the API authoring experience that Stoplight provides. Their Studio desktop app is like an Integrated Development Environment (IDE) for creating API specs. The graphical interface streamlines the ability to create API components while also allowing you to switch to editing the underlying raw YAML or JSON code when necessary. It also integrates nicely with Spectral so that your API specs are constantly linted for syntax errors and best practices.
Another great Stoplight feature is the way that it makes it effortless to visually see the various building blocks of your APIs, which helps enable code reuse and consistency throughout your APIs. The Stoplight web presence also acts as a portal for your API specifications, neatly rendering the associated documentation and making it easy to share with others. In addition to Stoplight, there are also other API platforms that offer much of the same functionality, such as Postman and SwaggerHub.
Shared Knowledge Space
While ideally all of your API contracts and documentation should live together, there may occasionally be a need to add supporting documentation in some sort of shared knowledge space or wiki such as Confluence or SharePoint. This will depend entirely on your team’s workflow and needs, but things like dedicated pages that give an overview of an API or feature along with XD artifacts and any other critical information can be helpful.
API Client
Another piece of tooling that’s helpful in following through with the API design process is an API client. Simply put, this is an application that can execute API calls. The most popular API client is by far Postman, but other alternatives like Paw, Insomnia, and Fiddler also exist.
While you won’t necessarily use an API client to create API specifications or documentation, it can be useful to create shared workspaces that others can use to test and get more familiar with using the API. Many API clients have the ability to import an OpenAPI specification, which makes getting started that much easier. You don’t need to wait until the backend team has finished development either. Most API platforms automatically generate mock servers from your API specifications, which you can interact with using an API client like Postman.
API clients also allow you to write tests against APIs. In addition to basic tests like status code checks, it’s also very helpful to implement contract tests. API contract tests will make sure that the response returned from the server matches the expected response according to the API specification. By implementing contract tests early, you can make it easy to verify that any backend code that gets deployed holds true to the spec, which will ensure a smooth integration experience for the frontend.
Conclusion
It doesn’t require a lot of fancy tooling to get started with an API Design-First process. Aside from the API-specific authoring tools like Stoplight, it’s likely that you are already familiar with or using many of these tools for your day-to-day software development process.
Are there any tools that you find invaluable to your own API Design-First process? I’d love to hear your recommendations! Feel free to drop a comment below or email me directly at tyler.milner@bottlerocketstudios.com.
