A first-hand design-first approach with Chelsea Hohmann, Engineering Manager at Stoplight.
There are countless ways to say that the best way to do something is to do it yourself: Eating your own dog food, drinking your champagne, and practicing what you preach. At Stoplight, we believe in doing just that when it comes to a design-first approach for our own API development.
We needed to design a group service that would have all the functionality necessary for our upcoming Workspace Groups project while using a brand-new microservices architecture.
We came to a business agreement about the API, what we needed to accomplish, and how to work across product, engineering, and our principal engineer to get things done.
Here are some of the key skills we learned during our first major API design-first project.
Define Your End Goals
Our goal, from an engineering perspective, was to move the needle toward a new microservices architecture. Essentially, the new microservices architecture we’re using requires us to have an OpenAPI spec; it won’t register an endpoint into the gateway unless it matches your spec. We enforce a design-first approach this way.
We chose to build custom logic into our own flavor of microservices to accomplish this goal. It goes through the spec and checks against the code, validates what’s written, and registers it into the gateway. If the code isn’t valid, then it won’t register into the gateway. If you’d like to find an endpoint in your spec but haven’t implemented it in your code, we automatically spin up a mock endpoint using Prism.
Implementing the microservices architecture that way allowed the engineering team here at Stoplight to ‘drink our own champagne,’ so to speak. We wanted to use our tools and get closer to our customers’ experience to better understand what they go through on an ongoing basis.
This is the first project implemented in this new framework that we’ve put together, and we are looking forward to testing it out in our next project phase.
Understand the Project as a Whole
First, we had to understand the Workspace Groups project and what functionality to include. We worked closely with our product manager to review his user stories to determine what to include in an early access release. We began to go through those user stories as a team to define the endpoints in the spec. However, we quickly found ourselves getting too far into the weeds since we had too many stakeholders involved.
Pivot When Necessary
We chose instead to go through those user stories with an eye for high-level endpoints and routes needed for each user story. We ultimately agreed that in order to increase efficiency (and cut down on various opinions) that one teammate would take the first pass at each of those endpoints to define elements like the body, the request, and all the lower-level details.
Once that teammate finished, we re-convened and reviewed it as a team. This way proved more efficient because we all had something to start off with and allowed our conversations to be more pointed and directed.
Choosing an Endpoint Wrangler
In this case, it made sense to have the product manager take that first pass, as our product managers are technically competent and view APIs as a product. They’re also the most familiar with both the user stories and the functionality that we were building.
Moving forward to our next design-first project, it makes sense to have the product manager take that first pass at identifying endpoints, and then bring the engineering team for discussion.
Highly technical product managers will not always be available, so we recommend appointing someone who has a good understanding of the project as a whole, the functionality you’re about to build, and also a solid working knowledge of APIs. This could be a team leader, for instance.
Collaborate Effectively and Look for Opportunities
Now that we’ve identified endpoints, our next stage was to design a better product through collaboration. Our product manager brought his ideas back to the table and we went through endpoint by endpoint, associating each endpoint with the user story it was meant to solve. We worked together to make sure that we covered all the use cases that we could think of and tried to poke holes.
During the collaboration stage, team members identified additional technical themes for our API, such as error handling and pagination. They took the first pass at what these themes would look like at Stoplight for every endpoint. This work wasn’t necessarily just for the Workspace Group’s project, but it also laid the patterns for every single endpoint from here on out.
Once again, the team utilized the same method: one team member taking the first pass and then bringing it back to the table for discussion. This encourages a culture of recognizing opportunity at the design stage for not only the project at hand, but across other relevant places in the business. Now we can support the same sort of error handling and pagination across all of our API endpoints at Stoplight, not just for this single project This allows our team to scale work accordingly.
Earn Governance Approval
We then established a rough flow of how to get the specs approved as part of our governance process. This means presenting our prototype specs to our head of Product, CTO, and principal engineer, acting as our API governance board.
For those who may be unfamiliar with a governance process – this check happens before you go into development; it’s that last quality check to ensure that all stakeholders agree that this is the way the API should be developed. This stage establishes a process to get future specs approved and get other projects going faster.
In the end, the governance stage produces a better quality product, saves engineering time, and improves overall business outcomes.
Back-End + Front-End
Then, we checked the approved spec in our Git repository. Once you do that, all the endpoints are mocked using Prism. The front-end development team begins development against those mocked endpoints while the back-end teams start implementing endpoint-by-endpoint.
We definitely recommend inviting your front-end developers to be part of the design and review process to create a better-quality API from the start. We believe front-end and back-end teams working in tandem save so much time while eliminating confusion. Our dedicated front-end engineer was also valuable in the collaboration stage.
Iterate and Improve
The next time we utilize the design-first process, we imagine it will be even further optimized and effective to meet our team’s needs. In the future, we will also create a Spectral ruleset, leading to better style guide enforcement across the organization.
As our very first front-to-back design-first project, this experience has definitely made us look forward to more design-first projects at Stoplight in the coming months.
