this is the CI job for publishing docs that i was thinking of: https://github.com/wikimedia/integration-config/blob/master/jjb/job-templates.yaml#L556

Given that automatic updating of the API Catalog page in the API Portal is desired, this can't simply be a normal page. Regardless of whether we get the information directly from the yaml files or from the Backstage-based API Catalog, we'll need a place to put the code that performs the requests.

I brought this up in today's Technical Discussion meeting. The two options that came out of this were:

1. create a service that generates the API Portal version of the catalog and use routing to make it appear to be part of the API Portal. That's how the RESTBase documentation is incorporated into enwiki:

https://en.wikipedia.org/api/rest_v1/#/
This page is actually generated by RESTBase, not MediaWiki, but appears under a en.wikipedia.org url (and shares a cookie domain with enwiki). However, as you can see, it does not have the normal enwiki header/footer. This option would mean creating and deploying a new production service.

2. create a new Special Page for the API Portal version of the catalog. This would allow it to appear as a normal wiki page, and would also let us conveniently take advantage of all our normal MediaWiki caching mechanism. This option would mean creating and deploying a new MediaWiki extension, presumably specific to the API Portal wiki.

Either of these approaches is technically feasible, but neither is trivial. I may do some exploratory coding locally to increase my own understanding. But let's talk again before we commit to either path. I'm not convinced that the return is worth the effort (both in terms of initial implementation and ongoing maintenance). I'm curious if a manually curated page detailing the most commonly used APIs would handle 80% of use cases. And a link from that manually curated page to Backstage might handle the other 20%.

@BPirkle thanks for looking into this and agreed, this does sound like the "juice is not worth the squeeze". I'm wondering if we've considered using a bot that could take our catalog output and write to a wiki page?

I'm sort of confused that it's this difficult to persist a list of items?

Thomas update:

• blocked on OAuth issues
• If we get Gitlab can use gitlab runners (basically redo)
  • there is a ticket which they will get to by February 23rd

Gitlab group request ticket -> T301164

Still have issues with OAuth. The permission to edit the page isn't in an actual OAtuh grants. May need to modify some of the settings of the API Platform. Likely need a config change in the API Portal.

When tested locally able to reproduce error, but got a different error.

Put this on agenda for Code Mob this week.

Still need to review as a team. Technically complete with a work-around.

Decided that what they had was sufficient.