Switch to automatic dependency injection of Utility APIs

[Rugvip]

Fixes #2182

Will add doc changes to this PR once we're happy with the changes.

Previous design was a single API registry where all APIs where wired up in apis.ts, simple but tedious and a lot of code required in the App.

This switches out to a more complex setup, but where the work of wiring up plugins in moved out from the app, making it significantly easier to add plugins to an existing app. apis.ts still exists, but it's only used for overriding the default api factories shipped in @backstage/core and each plugin.

Instead of directly instantiating all APIs and startup, we now lazy-load them as they are asked for. There's a quick sanity check at startup to make sure that there are no cycles in the dependency tree, but other than that failures will be encountered later. The instantiation is still synchronous, which is very much intentional, as I don't think we want plugins to do any kind of work at startup.

Couple of naming things to discuss:

• I opted for referring to the ApiFactories as just api in the external API. Since there's no other way to instantiate an API than using a factory, I felt that apiFactories and defaultApiFactories etc. were a bit redundant and went with the shorter form.
• Each ApiFactory earlier had an implements field, which I renamed to api. I think api captures the intention a bit better and is a bit more readable. I'm trying to skip having to think about "creating API factories", and make the mental model be that we're creating APIs. Another option here would be apiRef, since that's the actual value, but I feel that api is nicer, and typescript should take care of avoiding any confusion there anyway. It also aligns with useApi, where you're also actually passing in an ApiRef.
• Related to the above, the function to create ApiFactories is called createApiFactory. Here I did feel like createApi would be a bit too misleading, and I left in the Factory word just to give a hint at what it is we're actually doing.

[Rugvip]

Here's an example of what it looks like from a plugin's point of view

[Rugvip]

Not intending for this to build yet, will update docs and create-app etc once we've settled any discussions 😁

Please do review still :>

[marcuseide]

👍

[dtuite]

Will this require changes in plugins?

[Rugvip]

@dtuite preferably, but not immediately. Plugins can still choose to not supply default factories for their APIs, but then they have to be wired up in the app like before.

e.g. https://github.com/spotify/backstage/blob/62c2971a4aa923c1a49982d5bf2cba0145c62525/packages/app/src/apis.ts#L70

For the Travis and GH PRs plugins to be updated we'll need a new release with these changes, so that they can start exposing the factories, and then remove them from the app.

[dtuite]

@Rugvip we will work on that once this is merged. We're also working on migrating to the new routing API and tabs on the catalog entity page.

[Rugvip]

Adding docs in a followup PR so we can have a more focused review

[Rugvip]

#2334

[dtuite]

By the way, it would be great to get a release cut soon so people can more easily migrate plugins which are not in the monorepo over to the new APIs. 🤞

[Rugvip]

@dtuite Yep, just making sure #2200 is all good before we release, i.e. waiting for that to be closed.