Stoplight has always been an advocate for the design-first approach to API development. We’ve been “drinking our own champagne” for a long time now and have a fairly large library of internal-only API endpoints. With the release of our first public-facing API, we wanted to share our design process, what led to some of our key decisions, and the challenges we faced.
Defining the Problem
All software projects benefit from starting with your customers and the jobs they’re doing or the problems they’re having. API design begins the same way: You need to first clearly articulate who you’re trying to help and how you’re going to help them.
In this case, we knew our customers were frequently performing manual exports of their project files and we heard from many of them that they wanted to automate this process. Through customer interviews and early beta testers, we learned that customers were specifically looking to leverage their OAS and JSON Schema files in their downstream tooling and often as part of their CI/CD pipeline.
Stoplight’s process includes creating a “Project Charter” for any significant initiative so that we can work towards perfect alignment. As an API project, this charter included some API-specific categories but is otherwise just like any other project. It included:
- High-level goals, including customer goals (automating export), business goals (retention by way of useful integrations), and technical goals (creating a foundation to more easily build future Stoplight APIs)
- Specific customer requests, use cases, and edge cases
- Requirements breakdown, including user stories focusing on token generation, authentication, rate limiting and deactivation, analytics, debugging tools, performance expectations, and pricing and packaging
- UI mocks
- Stakeholder, Sales, and Customer Success FAQs
- Release strategy
- Testing notes
My advice to API Product Managers: Do this work before stepping into Stoplight. Once you have the first draft of your charter, humbly solicit vicious feedback from the widest audience possible including engineers, subject-matter experts, sales, support, QA, UX, and eager customers. After you have high confidence regarding the overall goal and intended developer experience (DX), you can start building out your API endpoints and various models in OpenAPI.
Designing a Solution
Stoplight customers come from diverse industries and range from small businesses to very large enterprises. Some customers have robust API programs with fully baked quality controls, while others are just starting their API journey. We knew immediately that the Catalog API needed to be reliable (which means highly performant and fault tolerant) and easy to use (which means leveraging industry standards) to attract adoption.
Reliability
First and foremost, an API needs to be accessible and secure. We explored a variety of mechanisms to accomplish this, including fine-grained permissions, personal access tokens, JWT-based solutions, oauth2 flows, and more. After debate, we landed on what we call Workspace Tokens. These bearer tokens are owner-created, have explicit read-only access, never expire, and aren’t attached to a particular user. We felt this struck a good balance between usability and security, but ultimately we want to build something useful for you. Would you prefer another auth mechanism or a different permission structure? Let us know!
Like any other product, APIs evolve. Unlike a typical web application, APIs don’t have the luxury of having a human controller who can adapt to new features and iterations intuitively. Instead, APIs need to launch with a versioning strategy on day one. By giving customers the ability to pin their integration to a specific version of your API, they have the confidence that a breaking change won’t halt their pipeline. Stoplight prefers the simple date-based versioning mechanism. The inaugural version of the Catalog API is `2023-07-12`.
Now that an export no longer requires manual button clicks, we needed to be sure that our underlying export engine could withstand the additional traffic. We took this as an opportunity to refactor some long-dormant dragons and add significantly more telemetry for monitoring and debugging.
With performance as a critical metric for success and a refurbished export engine, we wanted to test our system incrementally but also completely. We started by adding a new export option in the UI (which customers could disable if issues arose) to start generating traffic. To help us identify edge cases, we pointed our export towards “the most comprehensive, standards-compliant and up-to-date directory of machine-readable API definitions” (available here: https://github.com/APIs-guru/openapi-directory) and ran spectral on the original document and our new export. In many cases, we saw a significant decrease in the number of validation errors using the new export. In most cases, this is the result of cleaning up x-examples and other properties that changed from OAS2.0 to OAS3.X.
Easy to Use
Since our customers’ goal is to extract complete and working definition files (OAS and JSON Schema) and integrate them into downstream tools, the Catalog API needed to provide “bundled” exports that are entirely self-contained with no external references or dependencies. Rather than simply de-referencing $refs inline, the Catalog API creates reusable “components” (for OAS3.X) or “definitions” (for OAS2). This preserves the important parameters and model names used in various tools, such as SDK generation.
(original with Component Library reference on left, bundled export on right)
Similar to API authentication and versioning, there remained a few other “foundational” design decisions:
- Standardized error models – We went with RFC7807. However, I learned that it’s still best to create distinct models for different error cases, even if they have the same properties, because of how these models will be used by SDK generators.
- Rate limiting – Protect your own system and give your customers the information they need to throttle themselves. The usual x-rate-limit, x-rate-limit-remaining, and x-rate-limit-reset get the job done.
- Request Identifiers – You, your support team, and your engineers will all appreciate the added context that a simple Stoplight-Request-Id response header can provide. Include this identifier in all the relevant logs and train your customers to include it in your support requests to make debugging a breeze.
Fleshing out the endpoints is where you will likely spend the most time in the design phase. Since Stoplight itself is organized around Projects and their contents, we started by making /projects/ the primary resource. Specifying a branch (aka “version” for web projects) or commit is a necessary sub-resource, and we finish with an /export/ command followed by the file path of the target to export. Optionally, there is an include_internal query string parameter which will either include or exclude objects marked with x-internal (default is true). We believe the end result is intuitive and easy to cache.
(image via the Catalog API webinar)
Stoplight @ Stoplight
Stoplight’s development teams include an embedded technical writer to ensure the documentation remains relevant and current. In addition, we recognize that authoring documentation is an entire area of expertise with various tools and solutions, so our technical writers also provide invaluable feedback to help keep Stoplight competitive. To that end, there were a few challenges we’d like to address at some point that are worth mentioning:
- Externalizing previously internal API endpoints is tricky. To maintain a single source of truth, our internal OAS is now filled with x-internal tags. Ensuring future endpoints and models remain hidden is added overhead. Documentation that opts into certain content and automatically ignores everything else would be highly valuable.
- The Stoplight Platform has options for toggling versions in several ways, including branch-name and filename-based methods. For our own documentation, it’s not immediately obvious which option we’ll be choosing if/when we introduce another version.
- Sharing documentation to beta customers is a bit too restrictive in Stoplight. We temporarily set up a free workspace on another domain so that we could easily share early drafts with a handful of testers without spilling the beans on our main docs.stoplight.io website. In an ideal world, sharing private content would be as easy as exchanging a link.
Stoplight’s Discussion feature, which provides chat collaboration within Studio, was surprisingly helpful! Whereas Github and others rely on line-level code comments, which often lack context and require OAS experience, leaving messages in the form view makes collaboration much more accessible.
However, nothing beats the efficiency of synchronous API design reviews. Once or twice a week, we’d gather the team (engineering, QA, writers, etc.) and sit down with our API design guru, Jason Harmon. While Jason is Stoplight CTO and Head of Product (not to mention host of the popular API Intersection podcast), we asked him to wear the API consumer hat during our design reviews. If you’re not lucky enough to have a Jason of your own, consider asking an engineer on another team for a fresh pair of eyes.
If you’re interested after reading this blog, check out our Catalog API for yourself! If you’re a Pro Team or Enterprise user, you can log into your Workspace today and try it out. Let me know what you think!
