APIs and their documentation tend to get out of sync. And, it happens moreso than you may think. In fact, 75% of APIs don’t conform to their specifications, according to a recent report on API drift. API drift can cause mismatched developer-facing resources, developer experience issues, and even broken integrations and unhappy clients. What’s worse is that API drift is challenging to diagnose, making it a silent killer.

This is because API drift stems in part from a lack of visibility. “Based on our research, there is an ongoing disconnect with many teams between API architecture and API development,” says Jamie Beckland, Chief Product Officer, APIContext. “In particular, architects don’t have visibility into gaps between production APIs and their associated specifications.” When technology leaders can’t see how production APIs deviate from specifications, it’s challenging to determine what needs to change.

But the root causes go even deeper. Below, we’ll consider the key contributors to API drift and look at some ways engineering leadership can encourage their internal culture to be more intentional about API development. Hopefully, by following these tips, organizations will be able to retain more up-to-date resources and lessen the potential for API drift.

The Key Causes of API Drift

A handful of root causes are likely behind API drift. One standout point is the simple fact that API documentation is typically incomplete. Only 10% of organizations fully document their APIs, found a 2023 EMA report. Without a strong documentation culture or comprehensive API inventory management, it’s more common to see a disorganized use of service descriptions.

Furthermore, many groups are still early on in their API governance strategies. As the number of APIs increases within a company, those without established standards for maintaining the API lifecycle are more likely to experience incompatibilities or even see services turn into shadow or zombie APIs.

According to Lorna Mitchell, VP of Developer Experience at Redocly, API drift is intrinsically tied to a lack of comprehensive testing. Drift can occur for design-first APIs if there aren’t clear tests of whether what is built actually matches what’s described. This is a problem that can easily become endemic, she says. “Code gets duplicated, and the chasm widens.”

Not every organization enforces design-first expectations for API development or has mandatory specification compliance, either. As such, a lack of specification-first development is another likely cause of drift. “There are likely many APIs out there that couldn’t use OpenAPI even if they wanted to,” says Kevin Swiber, API Strategy Lead at Postman. “It will never get close to 100% adoption, and that shouldn’t be the goal.”

Rajesh Kamisetty, Digital Solution Architect, adds that drift arises from a lack of access to tooling and skills to produce quality OpenAPI specifications with schemas and examples. Non-existing or ineffective governance, as well as a general engineering immaturity and nascent documentation culture, compound the issue, he says. In this regard, API specification drift may just be a symptom of a wider problem.

All in all, API drift is an unintentional outcome that boils down to a lack of discipline, says Emmanuel Paraskakis, CEO at Level 250. “Discipline to design and deliver API products intentionally, with market feedback and with design artifacts that should be followed,” he says. “You are guaranteed drift when you can’t even agree on what you are drifting from.”

The Negative Effects of Drift

Without clear change management policies in place, APIs can easily drift from their documented form and function. When this happens, anything tethered to a “source of truth” becomes false as well. “The OpenAPI description doesn’t match reality, and so neither does your docs, your SDKs, or anything else,” says Redocly’s Mitchell.

This sort of drift can negatively impact the developer experience and productivity. “When the specification drifts, it stops being a source of truth,” says Kamisetty. “This can lead to consumers going down the wrong path, making invalid assumptions, resulting in productivity loss or worse implementation issues.”

Others agree that end developers typically take the brunt of API drift. “From our research, the end-user experience is dramatically impacted by API drift,” says APIContext’s Beckland. “Most teams hope that their API is self-serviceable, but when documentation does not align with actual functionality, it can be impossible for end-users to troubleshoot on their own.”

When API drift stunts the developer experience, it can produce some negative downstream effects for the business. Namely, lower conversion, high churn, low net promoter score (NPS), and a waste of resources, says Level 250’s Paraskakis. A lack of a well-maintained specification could also increase support costs.

Ways to Avoid API Drift

So, how can API teams avoid drift? What tools, processes, workflows, or cultural mindsets can help retain descriptions that match their APIs and vice-versa? Let’s look at some approaches API teams can use to proactively mitigate drift and preserve accurate API definitions that remain in sync.

Use OpenAPI as a Source of Truth

Minimizing drift requires building a culture of discipline and intent and centering changes on artifacts like OpenAPI documents, says Paraskakis. “Share and check in artifacts. Agree on what makes these artifacts publishable and worthy of building a product from,” he says. “Then use automation and tooling to ensure alignment with intent.”

Treat API Documentation Separately from Code

Kamisetty has a slightly different take, emphasizing that API specifications deserve their own repository and should be treated as standalone products. “API specs and documentation should be treated as separate from implementation code,” he says. “By moving them to their own repository, APIs can be treated as products, with dedicated documentation owned by technical writers or analysts who ensure they meet the needs of both business and consumers.”

Automate Documentation Generation

Tools like swagger-core for Java developers help generate OpenAPI specs from code annotations. However, Kamisetty cautions that this approach can still lead to drift if annotations aren’t consistently updated, and important context for consumers can be missed. Using tools to generate documentation from specifications rather than code could help keep APIs aligned with specifications.

Integrate Specification Testing into CI/CD

Running tests to verify API and specification alignment with every deployment is another effective practice. This could include conformance checks within CI/CD pipelines with every release. Tools like oasdiff can help identify differences between OpenAPI versions, aiding developers in spotting potential breaking changes before they reach production. Tools like Spectral or Optic can also lint APIs to ensure specifications conform to certain rulesets.

Use Contract Testing

Contract testing is another way to enforce adherence to specifications by verifying interactions. Contract testing tests production to make sure it matches its expected behaviors or the contract. As we’ve covered before, there are plenty of tools for contract testing, like Pactflow, Karate, Hypertest, and others. “Adding contract testing as part of the API description pipeline after linting and before any transform steps for publishing is a good approach,” says Mitchell.

Have a Repeatable Process for Updating OpenAPI

“This problem of drift is the biggest barrier to success with OpenAPI,” says Mitchell. “People try to lock the API code to its description and end up generating the OpenAPI description.” However, this can lead to downsides since there is typically minimal information in the codebase, and there is a lack of awareness on how to repeatedly modify OpenAPI descriptions after they are generated. This is an area where the new Overlay Specification is set to assist.

Be Flexible

While maintaining consistency is crucial, flexibility is sometimes necessary when production realities differ from initial designs. “Beyond tools, it’s also important for both sides to be flexible, as there are often practical reasons why API implementations differ from their original design,” says APIContext’s Beckland. “Depending on the variance, sometimes it makes sense to change the API, while other times the right answer is to change the spec.”

Is Mitigating Drift Worth It?

There are tradeoffs to instigating any sort of new technical practice. So, even if it is possible to mitigate drift, is it worth the effort? According to Mitchell, avoiding drift grants huge benefits since it means everyone is in sync. It makes integration easier and makes security and compliance requirements more auditable. These benefits seem worth the labor required to detect and remediate drift.

That said, the resources it takes to invest in mitigating drift will vary depending on the company’s size. While it’s relatively easy to deal with drift manually at a small scale, it will require processes to be put in place for large deployments. “At a large scale, this is unmanageable, and investing in robustness is absolutely worth it,” says Paraskakis.

Practically speaking, not all occurrences of drift will require sweeping responses. “Not every variance is equally important,” notes Beckland, who emphasizes the need for conformance tooling that tracks variances so teams can prioritize their actions effectively. “Product managers can often be helpful in deciding tradeoffs once they understand the surface area of the problem.”

“It’s worth giving it a shot to see for yourself if it works or not,” says Kamisetty. He suggests creating a drift index to quantify the amount of drift and establishing SLAs to address drift. Machine learning, such as through products like Traceable, can also help construct a schema and normalized endpoints that can be compared to an API specification, he says. Using versioning and automatically validating the specification against endpoints and payloads can also help mitigate drift.

Final Thoughts on API Drift

API drift is a multi-pronged issue with various potential root causes and an equally high number of mitigations. Since machines primarily consume APIs, drift can often go unnoticed, requiring focused efforts on detection and robust, adaptable maintenance processes.

One way to highlight the issue of API drift is to compare it to UI issues. “I’ve found that what resonates in my customer conversations is to compare API product design, delivery, and maintenance with UI-based products,” says Paraskakis. “No one objects to having a design in Figma, and design reviews and bugs filed if the UI drifts from intent.”

In addition to greater awareness, solving drift will also hinge on assigning ownership to fix it. As Beckland identifies, “Like many API issues, there are many potential owners, which often means there is no owner within the organization.” There’s already so much to manage with APIs — from design, style, and security to production readiness, marketing, and developer experience.

Adding drift management on top of that pile is more to ask, but it appears worth it from a user and business perspective. To get there, it’ll take tools to detect drift and repeatable workflows to keep things in sync. Culturally, it’ll require more knowledge-sharing and clarifying responsibilities.