[1] https://www.mediawiki.org/wiki/RFC

but would be great to put central in *the* new design

Perhaps i missed something. Does this imply there will be a new design?

I think it is an obvious and inevitable fact that every piece of software will eventually either die or get a next major release at some point.

The API is still in the 1.x days, which is cool because so far we've been able to keep "everything" compatible. At least on a higher level everything is still the same.

But especially now that the web is moving on and that we should optimize for JSON instead of XML (the whole 'content' vs. '*' mess for instance), and now that HTTP headers are easily usable from clients > I'd say we should make use of that - and we will at some point make use of that (I'm convinced of it).

.. But, no there is no active plan or schedule to go and redesign the API. This is purely for tracking purposes. The alternative would be to mark such bug WONTFIX because we don't want to break compatibility. Now they have a place to rest in piece until this becomes an active project.

Of course, if you (anyone) read this and think it is cool to work on a new API. By all means, go bunkers. Do keep discussion somewhere so that it won't be for nothing, but one certainly does not have to wait for the foundation to prioritize it if you feel like doing it.

The API is still in the 1.x days, which is cool because so far we've been able
to keep "everything" compatible. At least on a higher level everything is still
the same.

Well to be totally fair, "the" API isn't actually the first API (query.php !), but yes the api has stood the test of time quite well so far, even with its warts like '*' in json output.

However, I wonder if some of the warts of json output formatting could be fixed by simply making a json2 format instead of an entire API re-write.

The alternative would be to mark such bug
WONTFIX because we don't want to break compatibility. Now they have a place to
rest in piece until this becomes an active project.

I agree, this is a much better alternative then simply wontfixing said bugs.

The three things I like most about other APIs that I don't see in MediaWiki is:

• Request-header based formatting (instead of format=json, use "Accept: application/json", like $.ajax({ dataType: "json" }) already does. Optionally still allowing an override, though I don't think that should be necessary. Or alternatively drop all non-JSON formats as of API 2.0, may sound radical but I think its perfectly reasonable).
• Less complicated responses
  • don't wrap everything in { <actionname>: }
  • always include all properties, the <>prop thing is very annoying imho
• Simple directory-like urls (either through rewriting or with path info)

Inspired by BrowserStack's JSON API. Also contains handling for versioning, which would be the first level separator.

Format: https://localhost/w/api/version/action[/primary parameter | query string]

• https://localhost/w/api/1/opensearch/fooba
• https://localhost/w/api/1/sitematrix
• https://localhost/w/api/1/query/users
• https://localhost/w/api/1/query/users?usfilter[]=John&usfilter[]=George

Compared to:

• https://localhost/w/api.php?format=json&action=opensearch&search=fooba
• https://localhost/w/api.php?format=json&action=sitematrix
• https://localhost/w/api.php?format=json&action=query&list=users
• https://localhost/w/api.php?format=json&action=query&list=users&ususers=John|George

Anyway, just throwing it out there for feedback.

Fancy urls require extra configuration and are not always available. So while they have an advantage for user-facing urls I don't think we'll ever have a valid rationale for fancy api urls. It will only make using the api harder since clients will now have to figure out what format an individual wiki is using before they can even use the api. And they'll need to write the same thing twice to do it both ways.

Also you're focusing around the simple actions and forgetting how powerful the api format we have can be.

Allpages fed into prop=revisions as a generator to get latest revision data from all pages:
https://localhost/w/api.php?format=json&action=query&generator=allpages&prop=revisions

General siteinfo about the wiki, the namespace map, the logged in user information, and some of the latest changes to the wiki. All packed into one request.
https://localhost/w/api.php?action=query&format=jsonfm&meta=siteinfo|userinfo&siprop=general|namespaces&list=recentchanges

This part is something I'd actually like to see more. One advantage to wrapping everything in actionname is that it's completely possible to expand our current api to support multi-action api commands.

eg: Use action=query&prop=revisions and action=tokens at the same time to grab the revision text of a page and an edit token so that with your next request you can make an edit.

I had an idea lying around somewhere on how to make the api capable of doing more at once.

A few comments:

• While RESTfulish URLs look nice, MW is supposed to work without rewrites AND pathinfo, so I guess we'll have to stick with api.php?foo=bar
• Formats: my main concern is format=xml WHICH SHOULD BE KILLED WITH FIRE, unquestionably. An API simply can't be 2.0 enough with XML. However, JSON could be a pain to read when debugging API calls, so format=txt would be nice to have.
• Prop is a useful thing when you're requesting a shitload of information, especially when you're not on broadband. Also, some props require additional computations, so better exclude them if not needed. For example, I can't imagine action=parse without fine-grained props.

(In reply to comment #7)

A few comments:

• While RESTfulish URLs look nice, MW is supposed to work without rewrites AND

pathinfo, so I guess we'll have to stick with api.php?foo=bar

Yes.

• Formats: my main concern is format=xml WHICH SHOULD BE KILLED WITH FIRE,

YEESSS. I'd like JSON to be the only format just so we can get rid of all the formatting differences, but really what I care most about is for XML output to die in a fire already.

• Prop is a useful thing when you're requesting a shitload of information,

especially when you're not on broadband. Also, some props require additional
computations, so better exclude them if not needed. For example, I can't
imagine action=parse without fine-grained props.

Absolutely.

(In reply to comment #5)

• Request-header based formatting (instead of format=json, use "Accept:

application/json", like $.ajax({ dataType: "json" }) already does. Optionally
still allowing an override, though I don't think that should be necessary. Or
alternatively drop all non-JSON formats as of API 2.0, may sound radical but I
think its perfectly reasonable).

One feature of the existing API that should be a design goal of the new one is that it doesn't rely on any fancy HTTP features, so you can write an API client even if you can't:

• use HTTP methods other than GET and POST (e.g. JavaScript)
• set custom HTTP headers
• read custom HTTP headers
• read HTTP status codes

The API could *optionally* communicate things using these things (we currently set the X-API-Error header for instance), but you should be able to use it just as well without them.

So per that rule, formatting based on Accept: is evil unless &format= is also kept around. I also like the idea of just making it JSON-only.

• Less complicated responses
  • don't wrap everything in { <actionname>: }

You need to if you allow multiple actions (which I think we should).

• always include all properties, the <>prop thing is very annoying imho

It's good for filtering per comment 7, although the defaults could be tweaked.

• Simple directory-like urls (either through rewriting or with path info)

Evil because it reduces flexibility in terms of requesting multiple things at the same time, and requires path info. See also comment 6 and comment 7.

As posted in bug 39592, I have started the work on versioning. It will all be posted in the mediawiki-api labs. Any collaboration and thoughts are welcome. Here are my $2, with inflation, re above:

• JSON-only: there are 2500/sec JSON & 500/sec XML calls right now. I don't see a major benefit to switching, if only to majorly restructure output. If anyone has good suggestions, please start a bug or an RFC page? If its worth it, we could become JSON only... Still worrying if that's a step in the wrong dir.

• Don't like URL rewrites per above. Limiting.

• Same for verbs other than GET & POST. API needs to be functional and convenient first, pretty last.

• Header-based formatting - we could do it, but unless there are popular libraries out there that set it by default on all requests, what's the point?

• We need to streamline "continue" - as discussed in mailing list, there is no reasonable usecase to have independent generator= and prop= continues. Clients need very simple way of getting more data without even understanding the query. Similar to SQL - the request is passed as a string without comm lib understanding it, but the response can be handled in a structured way.

Bawolff, you rock, thank you for remembering query.php! I still have very warm feelings towards it... you know, first baby doesn't have to be perfect :)

The current implementation proposal is at http://www.mediawiki.org/wiki/Requests_for_comment/API_Future

Please comment on the talk page, or modify the page with any new ideas.