Please excuse the rough form of these notes. This a WIP (work in progress), feel free to comment and help me evolve this into what can hopefully be a good session.
The problem
The existing API was designed with editors and bots in mind. Throughout the history of mobile web and mobile apps we have hit many issues with using it.
- JavaScript clients have to deal with amongst many things the fact that lists are returned in objects due to how PHP arrays differ from JavaScript arrays. JavaScript Objects are not sortable in most clients. This means that the client usually has to handle sorting. To take an example in Special:Uploads on mobile when making a request to 'allimages' timestamp has to be requested despite the JSON 'ordered' in the response e.g.
- Obtaining simple information is not always easy e.g. to get the revision id of one page
- Features are missing and need to be added to support development (@Mhurd will be able to update the description with an example for this)
- It's not the most human friendly
A lot of queries are really difficult to build when you compare to rest apis. It's hard to work out how all the lego pieces fit together in the way you want them to. Especially when you have to resort to generators.
For example this query returns only an extract for 1 title
http://en.wikipedia.org/wiki/Special:ApiSandbox#action=query&prop=extracts&format=json&exintro=&titles=San%20Francisco%7CJapan
The end user has to work out exlimit=10 needs to be applied.
http://en.wikipedia.org/wiki/Special:ApiSandbox#action=query&prop=extracts&format=json&exlimit=10&exintro=&titles=San%20Francisco%7CJapan
Usually this is achieved by talking to @MaxSem or some other MediaWiki API developer. Relying on people is a big source of failure.
- We treat projects as separate entities with their own APIs. This makes things complicated when you want to merge content from Wikidata.org, Wikipedia, Commons for example.
Risks
It seems many people in the community/Foundation have views on the idea that we need an API but we all seem to be divided on what that should look like, whether it should be RESTful, what language we should build it in etc etc. We should be wary of this as this could easily turn into a session where everyone argues and says things are impossible based on the status quo and technical constraints.
Let's try and avoid any technical speak here, be clear that we should leave any technical constrains outside the room and explore what we /dislike/ about the API and what an API would look like from a frontend developers point of view if we were to build it from scratch now. Instead build a document that describes what a new API might look like. e.g. write an API specification
Session suggestion
- The Mobile App team has been complaining about the API for some time and we have an opportunity via the app to build a new API. If the app team was to commit to moving over to using such an API, what should that look for?
- The session should not be around anything technical and should be treated as a brainstorm session.
Structure
- Gather requirements
- [TBC]
Background reading
https://www.youtube.com/watch?v=aAb7hSCtvGw
Previous discussion: https://www.mediawiki.org/wiki/API/Architecture_work/Planning
Etherpad: https://etherpad.wikimedia.org/p/APIReform