In the second part of our blog series on API lifecycle tooling, Vanick discusses tools you can use to improve design collaboration for your APIs. Vanick recommends a combination of specialized standard documents and off-the-shelf tools to collect and collaborate on the requirements you need to build a great API interface.
This article is part of a blog series on API lifecycle tools. Click here for Part 1: Introduction.
The first step in the API lifecycle is design collaboration – working with your confirmed consumers as well as your internal teams to create an API interface that serves your consumer’s needs and, pragmatically, is actually deliverable by your organization. While you can, of course, send spreadsheets and documents back and forth to try to hammer out data requirements, we highly recommend you employ a standard set of tools to ensure that the proper details are collected and that your stakeholders, including your API consumers, can see exactly what you’re planning to build.
The first such tool you need is what we call the “design sketch.” This document is similar to a project charter in that it describes what you want to build. It begins by outlining the overall purpose of the API and the desired outcome of its use in terms of business value. The similarities end there, though, as the design sketch goes into more detail and identifies specific consumer use cases and the data that need to be exchanged to implement those use cases. While you can create the purpose and outcome sections internally, you’ll have to interact with your consumers to identify the proper use cases and the data requirement for them. The design sketch can also contain descriptions of any key requirements, such as regulatory restrictions or critical business rules. The design sketch is not a formal requirements document, nor is it a user story breakdown (it doesn’t contain acceptance criteria, for instance). Instead, it’s a higher-level description aligned to specific use cases with a strong business flavor.
Once you have the design sketch, you can move to a more technical level by constructing a requirements breakdown structure (RBS). The RBS is a hierarchical, visual depiction of the HTTP paths and operations in the API – because in 2017, you should absolutely be thinking RESTfully in your API designs. Each path and operation is followed by one or more specific use cases that it implements. The RBS is important for two reasons. First, it forces you to link use cases to RESTful entities and operations, guiding your design thinking before you even touch an interface definition document. Second, it can identify use cases that might need adjustment. Perhaps two use cases are served by the same endpoint and can be combined, or perhaps one is so different from the others in scope or domain that it should be its own API product instead. The RBS therefore acts as a bridge between the high-level business description of the API (the design sketch) and the technical interface definition, which you’ll construct as an OpenAPI (formerly Swagger) document.
Finally, for building and sharing your interface description, you need a collaboration site. The ideal collaboration site gives both internal and external stakeholders a low friction path to reviewing, commenting on, and modifying your OpenAPI definition. Optimally, it allows you to add documentation and discussion in a structured way without having to resort to e-mail. Finally, it should provide a visual, easy to understand view of the OpenAPI definition that isn’t simply looking at a page of JSON. A developer should be able to go to the collaboration site and quickly understand the operations in your API.
Working in Vanick Digital’s API practice, we’re partnered with several leading product companies in the API space to keep our finger on the pulse of the industry and inform client decisions where we work in an API program enablement capacity. If you’re looking for an off-the-shelf option for the tools mentioned above, for the collaboration site, we like Smartbear’s SwaggerHub. It’s an actively evolving product space and no tool is really closing every gap. With SwaggerHub, we’d like to see a stronger bias towards JSON (as opposed to YAML), better support for external references in the OpenAPI document, and more mature contextual help. All that said, it’s certainly the best tool we’ve found and provides an excellent collaboration environment. You can provide a link to your OpenAPI definition in SwaggerHub and your consumers can comment on sections or even individual lines to provide you with feedback. E-mail notifications for changes and comments help keep everyone in the loop. We like building our OpenAPI definitions in Visual Studio to start, benefitting from its superior Intellisense and schema validation, then copying it to SwaggerHub for collaboration.
The design sketch and requirements breakdown structure aren’t available off the shelf, though. They need to be tailored to your particular company and the data and process requirements of your industry. Vanick Digital can help you with this process with our API Kickstarter engagement; a key part of this engagement is working with you to build and/or implement these tools for your organization so you can execute design collaboration in a repeatable, scalable way.