Industry: Business/Productivity Software
Location: Atlanta, GA
Calendly is an easy scheduling platform that helps teams and individuals coordinate calendars. They’re also happy Stoplight customers.
In this case study, we spoke with Dmitry Pashkevich, an Application Architect at Calendly, about building a new API platform using a design-first approach. Dimitri focuses on Calendly’s integration workflows, product automation features, and public API platform.
When Calendly first decided to build their next generation API platform, they faced the challenge of a lot of internal APIs and a limited set of APIs that their public customers could use. They also were in the midst of transitioning from a monolithic to a service-oriented architecture.
“We needed a vision, a strategy; once we got that we started building a second version of our API that is more flexible, extensible, and more future looking,” shares Dmitry.
With development of a second generation API program came process changes. Calendly’s team was tasked with creating and adhering to solid design principles. At the time, Calendly was also transitioning internally from a monolithic to service-oriented architecture. So, these guiding principles that they established for their external APIs will be applied to all of their internal APIs that are consumed by different parts of their system.
Calendly’s major goals with their new API program were to:
In addition, Calendly aimed to establish principles that would be leveraged across internal and external APIs. It became clear that a coordination of business and technical objectives across the organization would be best served by a design-first approach.
“Before we could accomplish our goals, we needed to take the time to build a solid foundation; there’s just a lot to building a mature API platform. We’re trying to do it right and not boil the ocean all at once,” shares Dmitry.
Dmitry explained how there was frustration with Calendly’s own process and getting feedback from customers. As API consumers, they knew what to look for in a good platform.
“But I think as an industry we haven’t really been equipped with the best tools and processes to build APIs that are robust, scalable, and a pleasure to consume,” shares Dmitry. “For instance, a common problem that you see often as an API consumer is that the documentation is incomplete or out-of-date. The API is built as a series of responses to very specific customer requests. Then, you end up with this ‘Frankenstein’ API that is inconsistent, use case-driven, hard to maintain and keep up-to-date.”
“We decided to change our approach. Let’s use an analogy of visual design and the approach you would take to build end user features on a typical cross functional team. In this case, you would have a UX designer who produces high fidelity mock-ups. We haven’t really had the equivalent of that for APIs. And you’re really not setting yourself up for success by not having proper user interface and user experience design for your APIs,” shares Dmitry.
The idea of an API change started with product research based on customer feedback and Calendly’s internal strategy. The team that builds the public API has a product manager that often defines an idea and discusses it with the team.
From there, the team uses JIRA to manage their backlog, GitHub for version control for both their implementation code and the OpenAPI specification where the API designs are stored, and of course Stoplight, for their API design and development needs.
“Stoplight is our tool to facilitate the creation of the design document, and the collaboration around it. Running OpenAPI by hand is a little bit tedious—Stoplight helps with Stoplight Studio. We use the visual editor to quickly write OpenAPI,” shares Dmitry.
Stoplight Projects enables collaboration for the review process for Calendly’s API designs. One team member can produce a design for a new endpoint and before it’s ever published on Calendly’s documentation portal, another team member can preview these changes in Studio.
“This is helpful because you’re not just looking at code, but looking at generated documentation that Stoplight also offers. Once the review is done, someone presses merge and the new updated documentation is automatically published on the developer documentation, also hosted by Stoplight,” shares Dmitry.
“A big assumption that is often made in tradition from code-first to design-first is that you’re already treating your API as a product. If you don’t, that’s really step zero; your API should be a product. Treat your API just like your end user features that need customer feedback, channels for feedback, and have some kind of product strategy,” shares Dmitry.
Dmitry explains that the Calendly API team’s biggest advice is that one needs to decide for their organization the following:
“The design-first approach, for us, leads to a higher quality implementation, consistency, governance, and documentation that’s never out of date. That’s something that definitely speaks to developers both producing and consuming the API; documentation that’s never out of date and that’s high quality, detailed, all that good stuff that you expect from a mature platform.”
Get started with your design-first API approach. Create a free Stoplight workspace.