Create an API catalog in Compass

Question

We are experimenting with Compass as a potential implementation of our internal developer portal. One feature we have urgent need is to create an internal API catalog. While we can create a component catalog in Compass of various types and add "other link" to API specs, API is not one of the native types supported. As we are putting stronger emphasis on "API First", we'd like to treat API specs as first class artifacts. A few questions for the product team and the community:

- What's the best practice to create such a catalog in Compass? Should we use Service, Capability, or other types? Should we use labels?

- Is there plan to add API as a native component type in the future?

Thanks in advance!

Tongyu.Wang · Answer

Yes I agree that Service + labels is probably the best we can do to create an API catalog based on the current product capabilities, but also curious if the product team has any plan for API catalog as a first class feature.

Tongyu.Wang · Answer

I think that could be made to work with links to api specs and an agreed upon label so people can run a component search to see a list of components with apis, but that feels more like a workaround than an intentional feature. My preference would be that API is treated as a first class component type and maybe even with its own dashboard, something similar to Backstage.

Pavel Shkleinik · Answer

I'm not sure that there is a best practice, but my gut filling is that Service would be the closest to API type atm. Also there is Swagger UI Forge App (https://developer.atlassian.com/cloud/compass/integrations/integrate-Compass-with-Swagger-UI/) that can render your API spec in human friendly way.