Dmitry Pashkevich, an Application Architect at Calendly, about building a new API platform using a design-first approach.
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."
— Dmitry Pashkevich, Application Architect at Calendly
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:
Enabling more automation integration use-cases by adding more capability in Calendly’s APIs.
By building more SDKs and client libraries that developers could use to build their integrations faster with Calendly products.
Calendly’s goal with updating their API program had a focus on an easier self-serve experience for developers, so that when they go to the Calendly developer portal login, they can easily manage their apps and credentials.
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."
— Dmitry Pashkevich, Application Architect at Calendly
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. 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."
— Dmitry Pashkevich, Application Architect at Calendly
"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."
— Dmitry Pashkevich, Application Architect at Calendly
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 Platform. We use the visual editor to quickly write OpenAPI."
— Dmitry Pashkevich, Application Architect at Calendly
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 Stoplight.
"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."
— Dmitry Pashkevich, Application Architect at Calendly
"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."
— Dmitry Pashkevich, Application Architect at Calendly
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."
— Dmitry Pashkevich, Application Architect at Calendly
Learn more about Calendly’s public APIs or check out our other customer stories.
Create consistency and enable collaboration at your organization. Include Stoplight to help your team go API design-first.
Create a free Stoplight workspace
Industry: Business/Productivity Software
Location: Atlanta, GA
Employees: 200
Calendly is an easy scheduling platform that helps teams and individuals coordinate calendars. They’re also happy Stoplight customers.
