Page MenuHomePhabricator

Provide a Swagger-UI for exploring the core REST API
Open, In Progress, MediumPublic

Description

We have a Swagger-UI interface for exploring REST APIs exposed by RESTbase: https://en.wikipedia.org/api/rest_v1/

We want to have the same ability for APIs exposed by MediaWiki core and extensions.

Related Objects

Event Timeline

Change #863987 had a related patch set uploaded (by Daniel Kinzler; author: Daniel Kinzler):

[mediawiki/core@master] Add Special:REST for exploring REST API

https://gerrit.wikimedia.org/r/863987

There's some truncation of the bubbles at the top on "old vector".

"Contact the developer" is seemingly using "contact" from the rest.php, but this seems to be coming from wgEmergencyContact. The admin of the wiki is not necessarily the "developer" of the API...

License is unlinked, seemingly because wgRightsText/wgRightsUrl are both '', so I will fix that locally...

Screenshot 2024-04-07 at 18.58.19.png (640×1 px, 68 KB)

{
  "openapi": "3.0.0",
  "info": {
    "title": "ReedyDevWiki",
    "version": "1.42.0-alpha",
    "license": {
      "name": "",
      "url": ""
    },
    "contact": {
      "email": "<redacted>"
    }
  },

If we set them

$wgRightsText = 'CC lol';
$wgRightsUrl = 'https://creativecommons.org/licenses/by-sa/3.0/';

The output makes sense:

<a target="_blank" href="https://creativecommons.org/licenses/by-sa/3.0/" rel="noopener noreferrer" class="link">CC lol</a>

T362028: rest.php doesn't always expose license correctly wrt $wgRightsPage filed.

They're not cut off in Timeless, or in Vector 2022:

Screenshot 2024-04-07 at 19.32.55.png (83×426 px, 10 KB)

The layout of the page is less then perfect. For now, I was hoping to have it merged and enabled on beta and testwiki, so we can try it out. The CSS could definitly use some TLC from an expert, I just slapped it in there...

@Reedy On the patch you expressed concern about the size of the JS code that we'd ship. Do you have an idea of how we could reduce it?

I'm unsure whether to comment on the patch or here, as there is discussion in both places and it is a different set of people participating in each. I chose here because, from what I've seen, Phab tends to be more useful as a decision record, and also tends to be used by both engineers and non-engineers (EMs, PMs, etc.).

Regarding the idea in general, part of the point of the MW REST API, as I understand it, is to be more accessible, approachable, and familiar to people not already engaged with our technical ecosystem (vs Action API, which is great but definitely has a learning curve). Part of this goal is using tools that people are already familiar with. Swagger UI seems like one of these tools. And also like something that would be labor-intensive to build and maintain an internal, bespoke equivalent for. And if we're going to continue supporting and expanding use of MW REST API, we do need *something*, because right now it is a glaring missing piece.

I'm sure we could build something leaner if we built it specifically for our purposes (addressing the "non trivial increase in files we're shipping" mentioned by @Reedy). But anything we do would still be an increase. Does "non-trivial" here mean "alarming" or "impactful", or just "let's be sure this is the right choice"? If it is closer to being a blocker than just something to be aware of, how much smaller would an alternative need to be in order to be acceptable?

BTW, I also realize that I'm setting up a false equivalence by comparing "use Swagger UI in the way this patch does" vs "build a new thing from scratch". I'm sure there are all sorts of other choices. I'm not sure what they are, though.

Regarding naming, I'm not a fan of "Sandbox" because I feel like it implies the wrong thing (you can fiddle with it without affecting real data). When I joined WMF and first saw the Action API Sandbox, I assumed it would be a safe place to fiddle without hurting any live data. Fortunately, I saw the warnings before I broke anything, but I doubt all new people will, especially if the wiki they're messing with isn't in their primary language. We apparently don't have enough of that to feel compelled to rename the Action API one, but I'd still rather not perpetuate that naming. Remember, part of MW REST's goal, AIUI, is to be approachable to people who would not already be familiar with the Action API. So the fact that we use "sandbox" somewhere else with different expectations doesn't do those people any good.

I like all the alternatives better than "RestSandbox". I'd previously said elsewhere that "RestApiExplorer" was my favorite, but "RestRequestBuilder" is growing on me. Mostly because "RestRequestBuilder" does seem to make it very explicit that you're doing something that can affect actual data. I also wouldn't object to "RestDocumentation", which feels a bit more passive but still okay.

Regarding @Jdforrester-WMF 's comment regarding CVEs - yeah. I haven't looked closely enough to know how Swagger UI compares to other things in that regard, or what its recent history looks like. I do note that Swagger UI is an open source project, so there's the possibility that we could assist with issues. Not sure how realistic that is, though. Contributing to third party projects always sounds like a good thing to say in discussions, but I've rarely seen much of it in practice, anywhere that I've worked. Would Swagger UI be worse in this regard than alternatives (including home-grown ones)? What could we do to mitigate this concern? Would it be feasible to have a "kill switch" to temporarily disable the interface if we needed to? Turning off Swagger UI for a few days in an emergency situation doesn't seem like the end of the world. That wouldn't fix any damage already done, but it could limit ongoing damage.

@Reedy On the patch you expressed concern about the size of the JS code that we'd ship. Do you have an idea of how we could reduce it?

Do we actually need all the different files from the archive?

It’s unclear what they’re all for, but I’m guessing there’s numerous different copies in different formats…

Sure we want maps for the files we’re including, but multiple bundles? Standalone?

IMG_7193.png (1×750 px, 158 KB)

BPirkle changed the task status from Open to In Progress.May 2 2024, 3:24 PM
daniel raised the priority of this task from Low to Medium.Thu, Jun 6, 2:55 PM

Change #863987 merged by jenkins-bot:

[mediawiki/core@master] Add Special:RestSandbox for exploring REST API

https://gerrit.wikimedia.org/r/863987

Change #1046718 had a related patch set uploaded (by Daniel Kinzler; author: Daniel Kinzler):

[mediawiki/core@master] Special:RestSandbox: fix JS module

https://gerrit.wikimedia.org/r/1046718

Change #1046718 merged by jenkins-bot:

[mediawiki/core@master] Special:RestSandbox: fix JS module

https://gerrit.wikimedia.org/r/1046718