Articles
Building an internal API Catalog with Atlassian Compass
KATIE SILVER
PRINCIPAL PRODUCT MANAGER, ATLASSIAN
Executive Summary
Exec summary goes here
Time
Four-minute read. Less than 10 minutes to setup Compass.
Audience
You're part of a software delivery team and use APIs. Developers, engineers, and more can all benefit.
Prerequisites
- Get Compass - It's free to try and takes minutes to get started.
Building an accurate API catalog is a hard the problem
Over the last decade, we’ve traded big monoliths for microservices, distributed architectures, and autonomous teams. The benefits are real, but so are the consequences. Typed compilers and tests used to keep all the parts of a large codebase working nicely together. Today the boundaries are APIs, and it’s not clear if they’ll all fit together once deployed.
We know developers move faster, and teams ship better products when everyone understands how the APIs work, and when they change. It’s tracking and maintaining that documentation that is difficult.
Every organization is at a different level of maturity when it comes to mapping its services. On some teams, conversations on Slack bring alignment between the API producers and consumers. On other teams, the way each API works is written down when the service is created but never updated. If you have good processes or tools in place, every API is documented, and its changes are automatically communicated to the other stakeholders.
Wherever you are in that journey - Compass, Atlassian’s new developer platform can help.
Centralized API Documentation with Compass
Where should API documentation live in the world of microservices? Just because we build and deploy our services separately does not mean we want each service to have its own hosted doc site, or an OpenAPI file that lives in some obscure location. Teams want to bring together all that information together and make it searchable without a massive internal effort to build out an API registry.
Compass makes it easy to centralize all your API documentation in an hour, not a week or a quarter. You don’t need to upload documentation manually every time you make a change, you just need to connect your SCM (Bitbucket, GitHub, or GitLab) to Compass.
Within a few minutes Compass will scan all your repos for OpenAPI files and publish them to your catalog. All the APIs across all your teams become immediately centralized and searchable.
Discovering and integrating with an API
Imagine a developer picks up a ticket for building a new refund flow. They know they need to find the correct API to use to process a refund, but they don’t know where to start. In many companies, they would ask around on Slack and potentially wait hours for a colleague halfway around the world to answer their questions about which API to use. On teams with Compass, all this can be self-serviced. Developers can search for API endpoints and find the exact information they need right within Compass in just a few seconds. That means the developer searching for info finds it faster, and the team that owns the API in question experiences fewer interruptions.
Get notified about API changes
In the world of microservices, every service deploys autonomously, sometimes changing in ways the consumers need to know about. Luckily Compass doesn’t just know about your API documentation, it also knows how your API is changing over time. Every time a colleague merges a Pull Request that updates your API docs, Compass updates its version of the documentation, too, so the version developers see in Compass is always the most up-to-date API.
Historical changes even show up on the changelog page so you can see when in the past important changes happened:
When developers have the documentation they need, code ships faster
In Postman’s recent API developer survey 52% of developers said the biggest problem they faced working with APIs was missing documentation. Missing documentation makes development slower, onboarding new engineers more challenging, and software less reliable.
If you had to go build your own internal API catalog it would be a huge project, with a lot of moving pieces. We’ve done all that work for you, a centralized documentation hub is minutes away.
Give your team the information they need, and watch as they ship faster 🚀.