Provide an API listing at /api/
Closed, ResolvedPublic

Description

T95229 has established a general-purpose /api/ hierarchy, which is currently used by RESTBase at /api/rest_v1/. Before we announce this as the primary RESTBase entry point & dreprecate rest.wikimedia.org, it would be nice to provide some niceties like a simple HTML listing at /api/. We expect the number of APIs to be small, so a manually maintained HTML page should be fine.

@BBlack, do you have a preference for how we should go about this?

GWicke created this task.Jul 27 2015, 9:02 PM
GWicke updated the task description. (Show Details)
GWicke raised the priority of this task from to Needs Triage.
GWicke added projects: Traffic, Services.
GWicke added subscribers: GWicke, BBlack, Anomie, mobrovac.
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptJul 27 2015, 9:02 PM
GWicke triaged this task as High priority.Jul 27 2015, 9:02 PM
GWicke set Security to None.
GWicke claimed this task.
GWicke renamed this task from Provide a listing at /api/ to Provide an API listing at /api/.

Could we simply source it from a page on meta-wiki? (as in, rewrite the request internally to pull from meta-wiki?) Or something of that nature.

Restricted Application added a subscriber: Matanya. · View Herald TranscriptJul 27 2015, 10:38 PM

@BBlack, that sounds like a good idea to me. Do you think the backend Varnish layer would be the easiest / least invasive place for now?

it doesn't really matter where it's placed, but the frontend is probably more appropriate as it's where most mangling should occur.

Could we simply source it from a page on meta-wiki? (as in, rewrite the request internally to pull from meta-wiki?) Or something of that nature.

We do this for the www portals using protected pages on Meta-Wiki. I like this approach. I recommended doing something similar for stream.wikimedia.org (T70528).

GWicke added a subscriber: Spage.EditedJul 31 2015, 12:31 AM

@Spage, do you have the right to edit protected pages on meta?

I'll look into the Varnish config patch, but don't have the right to edit protected pages on meta.

Change 228426 had a related patch set uploaded (by GWicke):
Set up a listing page for /api/ in all projects

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

Change 228429 had a related patch set uploaded (by GWicke):
Add an API listing template to the allowed templates in extract2.php

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

There is now a bare-bones listing template at https://meta.wikimedia.org/wiki/API_listing_template. This page is already protected, and will be configured to display at /api/ with the two patches above.

Change 228429 merged by jenkins-bot:
Add an API listing template to the allowed templates in extract2.php

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

Change 228426 merged by Ori.livneh:
Set up a listing page for /api/ in all projects

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

@Spage, do you have the right to edit protected pages on meta?

Nope. This is all very cool.

Set up a listing page for /api/ in all projects

Is this expected to work on the beta cluster, e.g.http://en.wikipedia.beta.wmflabs.org/api/ ? I copied https://meta.wikimedia.org/wiki/API_listing_template to http://meta.wikimedia.beta.wmflabs.org/wiki/API_listing_template but see nothing. It's probably more work than it's worth to set it up.

The initial deployment only worked on the www domains. With https://gerrit.wikimedia.org/r/229219 now merged, /api/ should start working in more places. In theory, anyway. :-)

https://en.wikipedia.org/api/ and friends are now working properly. I think this task can be marked resolved/fixed.

Regarding Beta Labs support, I think a separate Maniphest task for supporting extract2.php (i.e., https://meta.wikimedia.org/w/extract2.php?template=API_listing_template) on Beta Labs would make sense here, if there's a real need for this functionality to be testable there. Given that the script is just echoing HTML to the browser, I'm not sure we need to use Beta Labs to test this.

GWicke closed this task as Resolved.Aug 6 2015, 1:26 AM
GWicke added subscribers: ori, Reedy.

@MZMcBride, for now the intention is just to be provide a friendly HTML entry point, which isn't critical and shouldn't need testing in beta labs. If we later decide to make this listing machine-readable by looking at the Accept header & returning JSON if requested, then that could be a good time to add tests, as clients would start to depend on it.

Closing as resolved.

@MZMcBride, @BBlack, @Reedy, @ori: Thanks for the help!

BBlack moved this task from Triage to Done on the Traffic board.Aug 7 2015, 4:41 AM