Evolving APIs with Confidence at MongoDB Atlas

Delivering a great API experience requires more than just exposing functionality. It requires a consistent design and a scalable process for ongoing improvement. With teams relying more heavily on automation and programmatic integrations, the way an API is designed can make the difference between workflows that “just work” and workflows that are fragile or surprising. For MongoDB Atlas, our unified data platform, the programmatic interface is the Atlas Administration API. This API provides developers with programmatic access to the features across the Atlas platform to deploy, manage, and scale their databases in the cloud.

As Atlas evolves, we at MongoDB have also evolved and formalized our approach to designing and developing our API. In this blog post, we’ll introduce the Improvement Proposals for APIs (IPAs), the guidelines that drive how we build and refine API resources across Atlas. We’ll share how they lead to faster adoption, more predictable integrations, and easier automation.

Before diving into our API framework, let’s briefly look at what makes an API experience feel cohesive and intuitive in the first place.

A cohesive and intuitive API experience 

MongoDB Atlas offers an array of features, including creating clusters, configuring database users, and managing backups. Our aim is that every API interaction feels cohesive and intuitive, regardless of which feature you use. To achieve this, the API needs: 

• Consistency: Whether you are creating clusters or managing complex workflows, consistent patterns across API resources help features work together smoothly. Consistent resource structures and uniform naming conventions make integration easier, and predictable behaviour reduces the effort required to connect workflows.
• Predictability: As the API evolves and new features are made available, consistent patterns make the experience more predictable. This reduces friction and removes guesswork when adopting new capabilities.
• Intuitiveness: When the API aligns with industry standards and best practices, it becomes easier to automate and scale. Familiar patterns help you quickly understand and reason about API behavior, improving the overall API experience.
• Extensibility: The API should support additive changes by default so that new capabilities can be introduced without breaking existing contracts or automations.

Unfortunately, achieving all of the above 100% of the time isn’t realistic. As with most things in software development, we need to balance tradeoffs. Instead of forcing users to migrate to new versions every time new features become available, we aim to ship additive changes that don’t break existing workflows. Meanwhile, if additive changes start to impact consistency or intuitiveness, we may introduce a new API version to make a more fundamental change. Together, these principles define what’s important and help us navigate API development as the platform grows.

API design patterns

The benefits of a cohesive API are clear, but to deliver consistency at scale, we need shared patterns that every API producer can apply. Design patterns provide solution blueprints that have already been evaluated and tested, shortening the design phase and allowing teams to move faster.

A key part of API design is shaping it with the user in mind, which, in our case, may be our customers calling the API directly. More commonly, though, in the world of APIs, our users are programmatic tools that will call the API on behalf of a human user. For IaC tools like Terraform, the API must function as a deterministic source of truth where resources are managed through state rather than actions. In this model, the API is composed of resources (such as users or projects) and a small set of standard methods (typically Get, List, Create, Update, and Delete). While these standard methods enforce a tight fit into a limited set of behaviours, they provide a consistent lifecycle interface for any resource, which in turn makes it easier to plug our API into programmatic tools.

Combining a set of well-known design patterns, such as resource orientation, creates a shared toolbox that API producers rely on to design and implement API resources. A collection of carefully selected patterns to support the intended users of the API results in a consistent API benefitting human developers and API tooling alike.

The improvement proposals for APIs

As the MongoDB ecosystem grows and evolves, we set out to build our own toolbox to formalize our vision for the Atlas Administration API. The goal of this API framework is to facilitate cross-team collaboration and help align all API contributors around an API-first mindset at every step of our development process.

To lay the foundation for our framework, we started by aligning on which patterns and API designs we wanted to promote. The result was the Improvement Proposals for APIs, or IPAs for short. The IPAs are a central set of API design principles that formalize our API vision, serving as the guidelines API contributors rely on to design, implement, and evolve API features.

In developing the IPA design principles, we didn’t set out to reinvent or overhaul our existing API. Our focus was rather on finding a balance between keeping what works and preparing our API for the future. The goal was to establish principles that are both practical and aspirational: 

• Practical: Many IPA principles document practices that many API producers were already following, formalizing unwritten rules into shared, accessible knowledge. By codifying these principles, we create a foundation for consistency across teams and in the future.
• Aspirational: We aim for our API to adhere to well-established industry practices that align with the broader expectations for how APIs should behave. By studying the principles employed by companies like Google, Microsoft, and Zalando, we ensure that the Atlas Administration API incorporates documented industry standards that have stood the test of time.

With these two core foundations, we developed a comprehensive set of principles that cover everything from documentation and naming conventions to resource-oriented design and declarative-friendly interfaces. With the vision formalized into the IPAs, we continued on our journey to expand our API framework by putting our design principles to use.

API validation

While the IPAs provide a clear vision for our API, we recognize that not every engineer needs to nor should be an API expert. Instead of using the IPAs as a manual checklist for API design and implementation, we set out to create a tool to automatically validate our API against the IPA principles. The IPA validation tool combines our OpenAPI document with Spectral, a customizable YAML/JSON linter. This combination was a natural fit in two ways. First, the OpenAPI Specification is the source of truth that powers customer documentation and automatic tool generation. Second, since the OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, Spectral was a great fit.

To turn our IPA principles into validation rules, we utilized the customization possibilities within Spectral to build our own rules and rulesets. Many of our rules validate the OpenAPI document for resource-oriented design. For example, the ruleset verifies that each resource path exposes a standard Get method that returns exactly one resource in a well-defined response schema, and that the corresponding collection path exposes a List method that returns a response with a paginated collection of the same resource type.

If a developer forgets to add a List method for a collection, or wires it up to a different schema than Get, the linter fails the build with a targeted message and a link to the guideline. This enables instant feedback and helps every API contributor adhere to our guidelines as they make changes. Additionally, we use our validation system to collect metrics and track IPA adoption over time. This data allows us to analyze where our API could use improvement and identify specific areas where we should invest our efforts going forward.

As of today, the IPA validation tool covers roughly 70% of our guidelines. These guidelines can be checked purely from the OpenAPI document, such as naming, structure, and standard methods. The remaining ~30% are more behavioral or conceptual in nature—for example, whether a resource field is considered client or server-owned. We address these guidelines earlier in the design process through reviews and our API Champions program.

API Champions

The final piece in our API framework covers more nuanced or complex API design problems. The program consists of a group of engineers from across the organization who, together with our API Platform team, work to become experts in our API standards. Not only do API Champions help us navigate the 30% of design guidelines that automation can’t catch, but the program also drives our entire API framework.

To truly scale the API-first mindset across all development teams, governance can't only take a top-down mandate from a single team. Instead, we want to influence how we work and enable all teams to own their API features with confidence in the IPAs. By training champions, we empower them to act as the first line of advocacy within their own teams. Team champions can combine their existing domain expertise with the IPAs to help their teams navigate API design and evolution.

Over time, and as the API Champions program grows, the group meets regularly to discuss evolving standards and complex design problems and share learnings. Combining the IPAs, the IPA validation tool, and the API Champions program, we ensure our process, guidelines, and automations are kept up to date and evolve as our needs change. This model ensures that API quality is considered at each stage of feature development, and fosters a company-wide commitment to delivering a world-class developer experience.

Seeing the impact

While this work is never finished and there’s always more we can improve, we’ve already seen concrete benefits from formalizing our API framework. Each piece across IPAs, validation, and the API Champions program works together to improve our API development process from design to release.

On the design side, our shared set of guidelines has reduced the need for one-off patterns and increased consistency in new API resources. Additionally, the IPAs and the API Champions efforts have helped us to ship more new features without the need for new API versions. At the time of writing, we haven’t required any new API version releases since the introduction of our API framework, reducing version bumps from three to four times a year to potentially once a year or every other year. Consistency improves the customer experience, and backward compatibility ensures customers can access new features without migrating through potential breaking changes when adopting a new API version.

While these improvements benefit anyone making a direct API request, the real impact shows up across the broader Atlas ecosystem. The Atlas Administration API is the backbone of a suite of downstream programmatic API tools, including the Atlas Go SDK, the Atlas CLI, and Infrastructure as Code (IaC) tools such as the Atlas Terraform Provider. For us, a solid, consistent API surface lets both customers and internal teams enjoy the same benefits. When we ensure contracts are predictable, we can more easily generate and update SDKs, CLIs, and IaC tooling. Through the API Champions program, we have increased awareness of the potential impact of an API change on all tools before it ships. In practice, that means features reach downstream tooling faster and behave more reliably once they get there.

What comes next?

Our full set of API design principles is published publicly at mongodb.github.io/ipa. If you’re looking for inspiration or want to dig into the details behind the patterns we describe here, that’s where you can explore the guidelines and examples. To go a step further and enforce these rules in your own OpenAPI documents, you can use the @mongodb-js/ipa-validation-ruleset NPM package, which bundles the Spectral rules we use to validate the Atlas Administration API itself. If you would rather create your own validation ruleset, you can explore the source code for the IPA validation ruleset in our public GitHub Repository.

Inside MongoDB, we’re continuing to invest in tooling that makes it easier to design and evolve APIs with confidence. That includes deeper integration of the IPAs into our processes, as well as AI-assisted design and review workflows that can flag inconsistencies, suggest improvements, and help teams reason about changes earlier in the process.

Each part in our API framework forms the foundation for our API vision of a cohesive API surface across Atlas. As that vision expands beyond the Atlas Administration API, this framework will continue to guide how we design, validate, and ship APIs so that every new capability feels like a natural extension of the ones our customers rely on today.

Acknowledgments

Thanks to Sophia Terry, our intern on the API Experience Platform team, for contributions to the early development of this post and for driving the work to improve our IPA validation ruleset and publish it as an open-source NPM package.