Page MenuHomePhabricator

MediaWiki Action API is a unique API specification
Closed, DeclinedPublic

Description

Problem
I am new to MediaWiki's Action API. The Action API is extremely flexible and allows you to do a great number of things (that I honestly do not fully understand). However, the learning curve is somewhat steep. It can be difficult to figure out how to do certain things, and difficult to figure out that you cannot do certain things. The Action API also does not seem very consistent. Parameter names, ordering, responses etc. can be different depending on the module or even submodule.

The Action API feels completely unique to MediaWiki with it's own specification. The steep learning curve makes it difficult for developers (even experienced developers) to get acquainted with the API (especially with the subtle nuance that isn't well documented).

Solution
It might be worth considering using a standard API implementation instead of our own custom implementation. Standard implementations are more well-known, typically have implementation libraries already available, and are typically provide a higher level of flexibility and/or cacheability.

It also would help avoid bikeshedding.

API Standards:

There are probably other specifications available that we ought to consider, but avoiding the custom specification would resolve a lot of issues that new developers encounter and make MediaWiki's Web API more approachable to outside developers, and allow existing standard libraries to work seamlessly with our API.

Event Timeline

Anomie added a subscriber: Anomie.

No, we're not going to rewrite the entire API in some other random framework just so you don't have to read documentation.

No, we're not going to rewrite the entire API in some other random framework just so you don't have to read documentation.

Specification, not a framework. And it's not about me, it's about making MediaWiki more approachable to new engineers, but if that's not one of our goals then you're right, it's pointless.

I just assumed that we wanted to make things more friendly to new engineers, my mistake.

This comment was removed by dbarratt.

Also, this means we are rejecting the need to handle complex queries through the API and would prefer for people to create their own (less optimized) API's in Toolforge.

dbarratt updated the task description. (Show Details)

Opening this back up since:

No, we're not going to rewrite the entire API in some other random framework just so you don't have to read documentation.

is illegitimate, rude and hostile.

However, the learning curve is somewhat steep.
It can be difficult to figure out how to do certain things, and difficult to figure out that you cannot do certain things.
The Action API also does not seem very consistent. Parameter names, ordering, responses etc. can be different depending on the module or even submodule.

To me the answer to none of these things is a rewrite.

the subtle nuance that isn't well documented

So file tickets about that.

It also would help avoid bikeshedding.

This may be something of a lost cause.

No, we're not going to rewrite the entire API in some other random framework just so you don't have to read documentation.

I think you misunderstood the ticket. There are totally legitimate reasons to decline this ticket, but this isn't one.

To me the answer to none of these things is a rewrite.

To be fair, I didn't say anything about a rewrite. Is that what it would take to implement the solution I came up with?

I'm open to alternate solutions if you have any. :)

dbarratt added a subscriber: bd808.

I think this issue is legitimate and deserves a legitimate response. While T181257 and this ticket potentially share the same solution(s), this ticket has a different problem that needs to be solved. Unless @bd808 thinks the problem(s) from both tickets should be merged together and solved together.

Unless @bd808 thinks the problem(s) from both tickets should be merged together and solved together.

As currently formulated, I really don't think either ticket is solvable. They are both vague requests for large scale change with little or no rational analysis of the implications of those changes (both favorable and unfavorable) to MediaWiki, the Wikimedia movement, and the literally thousands of applications built upon the current Action API constructs.

The "unique API specification" claim is in and of itself confusing and potentially misleading. One proposed example, JSON API, is an interoperabiltiy spec and the latest incarnation of a dream that tooling providers have been chasing with SOAP, CORBA, and other protocols for decades. The query interface of the Action API could possibly be wrapped with any of these protocols, but it is unclear to what end other than possibly removing a very small amount of boilerplate needed to encode requests as the current GET/POST parameters. The suggestions from T181257 which are also proposed as a solution here are very specifically graph traversal query languages which would be incapable of providing any editing features which are actually a fundamental use case for the Action API.

Neither of these directions is necessarily bad, but the use case analysis of how either could replace the existing functionality and extensibilty of the Action API which has been in continuous development and use since at least 2006 is missing. This particular ticket is asking for creation of a new remote API of interacting with MediaWiki in the vein of https://www.mediawiki.org/wiki/RESTBase and the ideas that have been promoted there to implement a REST API for improved cacheability primarily of page content oriented actions. I would suggest taking the MediaWiki-API tag off of this and pursing it as an TechCom-RFC if you are truly interested in finding a solution to one or more large classes of problems that you feel are unable to be resolved via iterative extension of the Action API.

@bd808 Thank you for your detailed response, I really appreciate it.

The MediaWiki API is about 30.000 lines of code, not counting extensions. The COCOMO estimate for a rewrite would be seven man-years. You say you are not proposing that, but it's hard to see what you are proposing then.

The (somewhat) specific problems you mention seem to be fairly unrelated to the proposal.

  • Inconsistent parameter names etc. are the result of a large codebase being grown organically and without strong direction / oversight over a long period of time. I'd say that's less of a problem these days, so it's mostly an issue of cleaning up technical debt. (Replacing the whole with something else is one way of doing that, but not exactly the safest or most effective.) Making a list of issues would be a good start. https://phabricator.wikimedia.org/maniphest/query/70VwG0qCZnUx/#R has some but not that many.
  • Lack of good documentation is an ubiquitous problem (the action API actually does much better than most), but the obvious solution there would be to write more / better documentation. Or at least explain what kind of documentation is needed.

Writing client libraries which map the API conventions to some different set of conventions is also an option (see e.g. the generators in Pywikibot).

Both https://phabricator.wikimedia.org/T180096#3804495 and https://phabricator.wikimedia.org/T180096#3823833 are great replies.

In my opinion, it's fine for this task to remain open. However this task is currently very unlikely to result in any positive action without a substantial increase in clarification and problem definition. There's currently such a mix of unfocused thoughts in the current task description that it's difficult to adequately respond to them. For example, if you're saying "new and unfamiliar APIs are annoying to learn" in this task, this is undoubtedly true and some people have tried to solve this by creating tools such as https://www.mediawiki.org/wiki/Special:ApiSandbox.

This is not to say that brainstorming and drafting are bad (they're not!), but as a request for comments, this task is way too early and poorly defined.

It'd be nice to know who the experienced and struggling developers referenced in the task description are.

I'm not sure what this task is about, but it seems that the underlying desire for the proposer is to have a familiar interface for the API. This seems typical territory for a client library: many like to access MediaWiki data in a pythonic way, so they choose a library and access a subset of the MediaWiki API by that method.

daniel added a subscriber: daniel.

Last Call for comments: As per the triage session on January 10, TechCom propose to decline this RFC as proposed, for the following reasons:

  • The RFC does not provide convincing arguments or evidence that the proposed alternatives would actually address the stated problem. In particular, using a more standardized JSON format does not by itself address the complexity of the underlying data model and action model.
  • The RFC does not provide a concrete plan for how current functionality would be provided using the proposed new interface. It does not make clear how a different format for API calls and responses alone would improve cacheability.
  • The RFC does address the question of migrating existing client code and preserving backwards compatibility for 3rd tools, on-wiki gadgets, client libraries, etc.

If the given issues are not remedied by the TechCom meeting on Jenuary 24, this RFC will be declined as written.

Please note that even if this RFC is declined as written, future RFCs for improving, augmenting or replacing the current web API are still welcome.

This RFC is declined as proposed, per the Last Call from January 10.

TechCom recognizes the need to improve our API, and make it more consistent in terms of request parameters and response formats. This was discussed as part of the session about evolving the mediawiki platform at the developer summit, see T183313#3930040. Designing a consolidated REST API is expected to be part of the platform evolution program that the ATWG is currently working on, see https://docs.google.com/spreadsheets/d/1DDtO5v5GAtNSRiKHyii8Kv-kNsar25Ac5Z0WIrU_Mt4/edit#gid=71523076