How Atlassian Is Approaching API Governance

The phrase ‘technology governance’ often conjures up images of bureaucratic red tape that can make even the most seasoned programmers bristle. Yet, governance is looking like an attractive (if not necessary) course of action to reduce technology sprawl, rising technical debt, and inconsistent development patterns. And arguably, nowhere is governance more needed than with API design and development.

One organization that has been experimenting with internal API governance is Atlassian, specifically the R&D division. Atlassian maintains what they call Extensibility Standards within an internal governance platform, and the idea is to apply these rules to conduct automated conformance checks against new APIs.

I recently chatted with Dugald Morrow, Developer Advocate at Atlassian, to learn more about their strides toward encouraging standards for their internal APIs. According to Morrow, their process is still ongoing but has already shown promise, resulting in less undesirable API changes and instilling an “ecosystem DNA.”

The State of The API Portfolio

A lack of API standards is a common scenario across today’s digital organizations. “It’s a big problem as it’s a lot to tackle,” says Morrow. For instance, a lack of alignment around API change management can have negative downstream consequences like broken integrations.

Before implementing a governance strategy, siloed API development was an all-too-common dilemma at Atlassian. “Our R&D teams would accidentally break APIs too often, which impacted both our partners and customers,” says Morrow. “There were quite a few causes of this, but it boiled down to R&D teams operating independently and therefore missing steps.”

A lack of standards around change management hurt the Atlassian ecosystem, but discovering the cause wasn’t apparent initially. “We knew we had a problem with change management, but it took a while to realize that a lack of standards, practices, and tooling was the root cause.” This recognition largely came from the bottom-up, he adds.

Introducing an API Governance Framework

To address these issues, Atlassian is producing its Extensibility Standards, which are documented internally and enforced automatically against APIs as they are developed. To enact this, Atlassian’s automated API governance framework involves a handful of components.

First is documenting the rules. The Extensibility Standards are privately documented at developer.atlassian.com. The platform contains standards, such as guides, rules, authentication standards, and definitions, in a Bitbucket repository in structured JSON and YAML text files, says Morrow.

Next is providing easy editing capabilities for the rules. The repo contains a web app that allows editing standards, with guidelines for maintaining them, says Morrow. It also provides continuous integration processing to automatically generate Extensibility Standards documentation.

Then, the idea is to automatically run governance checks. According to Morrow, Atlassian has a Node/TypeScript report on the conformance to rules. The process uses a specification-driven approach to lint rules. As he describes, this involves building a Spectral ruleset from the standards, retrieving all the OpenAPI specs of various products and services, running Spectral against the rules, and reporting the results to a data lake and internal Confluence pages.

The platform also provides methods for managing changelogs. “The CI processing builds reports identifying the health of changelogs and occurrences when changelog entries were announced late,” says Morrow. An internal application also provides helpful tooling to preview changelogs before they are published, assess the impacts of API changes, and calculate deprecation periods.

A big goal is to provide actionable data. The team behind the Extensibility Standards has thought much about streamlining the API lifecycle and providing helpful reporting and visualizations. “There is much more to do, but the intention is to automate as much reporting as possible and then have teams analyze the data during their TechOps meetings,” says Morrow.

Realizing the Benefits

Atlassian is early in its journey, but teams have already seen tangible outcomes from doubling down on API governance. One such outcome is a decreased number of incidents, says Morrow. “There are fewer regrettable API changes and consequently less negative impact on partners and customers.”

Another positive result is the impact on collaboration. “There is also an increase of ‘ecosystem DNA’ within R&D teams because of practices like request for comments (RFC), which results in R&D teams engaging with partners during the API design phase,” says Morrow.

Last but not least are the potential productivity benefits. “I would hope that overall productivity is improved due to better tooling and better ways of working,” says Morrow. Developer productivity engineering has been a hot topic throughout the world of tech lately, and this ambition is not lost on the API community.

Learning From Atlassian’s Strategy

So, what can engineering leaders in other companies learn from Atlassian’s foray into API governance? Here are some tips for governing a burgeoning API portfolio.

• Enact change from the bottom-up: Looping in developers early in the process typically yields the best results. “We’ve taken a bottom-up approach whereby we’ve built the standards necessary to address pain points, and we’re now bringing this together to form a platform of standards,” says Morrow.
• Explain your rationale: Getting folks to adopt new rules can be challenging, especially when they don’t have context. Therefore, Morrow recommends making the API standards attractive and explaining the rationale behind these rules.
• Provide great tooling: Provide tooling to make it easier for developers to implement and edit your rules. For instance, consider constructing an internal API governance framework. Atlassian’s automated approach to its Extensibility Standards eases how maintainers interact with the platform.
• Automate everything: As we’ve seen, Atlassian has adopted rigor in its internal tools, creating an integrated platform with a high degree of continuous automation, from updating rules to enforcing them, producing reporting, and more.

All in all, getting everyone on board with extensibility standards will take effort, but the payoff is worth it. “It’s a lot of work, but I think our approach has worked so far,” says Morrow.

The Rising Need For API Governance

Atlassian’s experimentations with API governance is an interesting model to consider. Although it’s still a work in progress, the internal platform intends to bring a collaborative, cross-team method to managing API standards.

Across most organizations, the number of APIs being developed shows no signs of shrinking. Plus, large companies now contend with various API styles, and engineers often juggle different lifecycle management tools concurrently.

To respond to the state of things, we need more than a written style guide or recommendations. Helpful technology, perhaps in the form of internal platforms like Atlassian’s, will be required to enforce and iterate API standards. This should bring more consistency to the development culture and promote a healthier API mindset.