Whiteglove API Design Experience

DevLab continues to evolve. One change has been a tighter integration between SwaggerHub and the platform. When I connected my API contract via a webhook, I could begin to visualize a potential workflow. Today our developers use Azure DevOps, builds, releases, and configure servers via all manner of tooling. It is a lot to maintain over time. Standardization saves time and headaches. You can skip learning the nuances of how each team does something slightly differently. This is a stark difference from DevLab. While I broadcasted, internally, the importance of API-First I neglected to show how we can manage it. Now I have a better understanding.

Start with the API Contract

It all starts with editing the contract in SwaggerHub using their YAML editor. The YAML is daunting at first. Maybe it would be easier to use a tool like stoplight studio to iterate locally first. In time your team agrees to the API design. You save your changes. You click the publish button under the version dropdown, and your API is live.

Accessing DevLab to create your project

Once your contract is available and public, you can create a new project in DevLab. Maybe one day, you can also choose what client API SDKs you want to be included in your new project. Either way, you are taken to your new project summary page. You can pull your code down locally and implement the functionality of this API. Either through iterating on it with your team or deploying code to production. You learn that your API is missing something important. You and your team go back to SwaggerHub and add the missing routes to the contract. Publish this new version. Now you can see the contract changes come through on the swaggerhub branch you can merge in at your leisure. When you’ve implemented this extra machinery you are ready to go to production with this new version.

Breaking API Changes

A big question I have is how do we deal with breaking API changes in this new paradigm? I do not have an API gateway which could make this less painful. We could run many versions of the APIs. Many API versions would add maintenance overhead until consumers migrated to new API versions. We could make new versions of the APIs backward compatible and forcefully upgrade the consumers. We could even define a new workflow where we fork the original API. Then make the contract and functionality changes. It remains unclear yet which workflow we prefer.


I am hopeful this workflow will fulfill the goal of API-First design. The portal, as it stands today, focuses on creating a project. Skipping API contract design until later. Design-free might be one of several options if a team decides they prefer it is too much overhead?