Manage API specifications
The API specifications feature helps your teams manage and quickly find specific endpoints associated with components in Compass. Developers can use the feature to easily reference accurate API specifications in a centralized location.
After you connect a code repository from either Bitbucket or GitHub, Compass automatically scans for associated API specifications in the background, then displays them within each component’s sidebar. How to import components from other apps
The feature is split into two helpful capabilities:
Endpoints: This table displays all endpoints associated with the component. It includes method, path, summary, and the date the endpoint was last updated.
Changelog: View endpoint changes over time with a chart visualization. You can track endpoints that have been added, changed, or removed, based on date, then select the hyperlinked path for more detail.
The feature helps your team view endpoint details including recent changes, organized by date. When you connect a repository, we detect and add any associated API specifications to the relevant components in Compass.
Find the API details you need
When you view the API feature, you can browse and find the right endpoint to use in your work, and check when it was last synced so you know the accuracy of the API specification. When you drill down into a specific endpoint, you can view relevant code snippets, responses, and requests
You can make documentation accessible to the developers who need it when they need it most, reducing the lead time it takes to find answers to questions about how the API works.
Review API specifications
When API specifications are added, Compass detects and highlights code errors in the newest version, which temporarily pauses the automatic scan. Once those errors are fixed in the source repository, the scan will resume.
This makes errors easier to fix, and helps ensure that your team’s API specification is up-to-date, accurate, and in sync with your components in Compass.
Before you begin
Before you can view API specifications in Compass:
Install your SCM app in Compass. Select Apps from the top navigation and select Install on the app’s tile.
Select Configure on the app tile and connect Compass to the account containing your component’s repositories.
When you connect a Bitbucket or a GitHub repository, Compass automatically scans the SCM app for API specifications. If the scan finds API specifications in your repository, you can view endpoints on relevant component pages.
If Compass finds any code errors in the API specifications, an alert appears in the Endpoints section for your team to review. These errors need to be fixed before we can sync your updated API specification with your components in Compass.
View an endpoint's request and responses
Go to your component’s Overview page.
Select API specification from the sidebar.
In the endpoints table, find the endpoint you want to view.
Select the hyperlinked path to view endpoint details, such as the request, responses, and code snippets.
In addition, you can select hyperlinked paths in the Changelog tab.
You must have full user permissions to access the API changelog. Understand user roles in Compass
View a component's API details
Go to your component’s Overview page.
Select API specification from the sidebar.
The Endpoints tab displays endpoint details, including method, path, summary, and the date the specification was last edited.
Select the Changelog tab to view endpoint changes based on date and over a six-month period of time.
Change a source repository
Go to your component’s Overview page.
Select API specification from the sidebar.
Select Change source, then add a different repository, the path, and a default tag. Note: The tag is usually your default git branch.
Select Save.
Was this helpful?