Status: Open for comments

Need

Current support for Kind: API in Software Catalog is limited to a standalone API Specification file either mentioned completely inline the Catalog definition or referenced in URL with $yaml / $json / $text

It's a standard practice to write API specifications in multiple files and references them with $ref in the spec files.

While doing a Proof of Concept with three use-cases which are discussed within the Backstage Discord server, it is concluded that the best solution would be to upgrade the Catalog processors to handle this problem.

Sample Error Message we got by doing a $ref to a file present on relative path to the registered catalog file is attached below:

Proposal

The catalog processor can be modified to create a standalone specification in the backend by combining all the $ref references (to a file reference with a path on the VCS or a URL from a host which is in the reading list of Backstage applications). This standalone specification within a catalog definition can be then registered on the Backstage UI successfully.

Alternatives

We are adopting Backstage and would love to see all our APIs on the platform.

If we go with the current product, we would have to spend time and change all our API specifications into a standalone file.

Risks