Wikimedia Developer Summit/2017/Action API


 * Topics for discussion:
 * Overview of the Action API
 * Action API is the older version of the API (as opposed to the Restbase [rest-based] API: https://www.mediawiki.org/wiki/RESTBase )
 * Mostly used by bots and user scripts
 * one of the more useful tools is the api sandbox Special:ApiSandbox
 * A recent change with the API is i18n error messages
 * API workboard backlog


 * Q: As a newish person, why do we have two APIs?
 * A:  Comparing and contrasting the different APIs:
 * Action API: https://www.mediawiki.org/wiki/API:Main_page
 * The very first API was query.php, correlated to the query action in the action api.
 * Later renamed to api.php
 * Its scope was broadened to include edits (so screen-scraping wasn't required) so it was renamed and rearchitected.
 * Restbase API: https://www.mediawiki.org/wiki/RESTBase
 * A few years back there was a push for a more REST-oriented API to do a slightly different set of things.
 * Parsoid, for example, is only available in the REST API.
 * One major motivation is caching.
 * The REST API is more one-thing-at-a-time and tries to make responses cacheable, whereas the action API is batched and harder to cache


 * Q: Is the plan to move away from the action API?
 * A: Yes, but we try to maintain backwards compability and functionality (this was probably misunderstood)
 * --- [post-meeting edit: The "Answer" here is incorrect, I don't know where it came from. No, there are no plans to move away from the action API. If I recall, the discussion was around the fact that the action API and REST APIs serve different purposes and both are useful for different kinds of tasks.]
 * Q: Do people find it OK to have to use multiple APIs, or would it be better to proxy one through the other?
 * A:
 * There's a benefit to having multiple
 * but we do have to be careful about accidentally creating footguns if there are API inconsenticies (e.g. assumptions for REST API that aren't directly applicable to a proxied-through Action API
 * Two examples of proxying is ORES via action API, and some PageView stuff in the works
 * Q: Is there a plan to use these APIs for frontends?
 * A:
 * There are gradual changes towards API-driven frontend
 * [post-meeting edit: This doesn't really correctly characterize the discussion as I remember it. The discussion along these lines was referring to things like the mobile apps that are API-driven, but not blue-sky proposals some have made to make an API-driven web frontend.]
 * There is research under way to look at offline use cases / progressive web apps
 * Question for the room: does anyone hit the upper limit of the Restbase API?
 * Discussion:
 * Parsoid is the largest consumer of the Action API
 * Is that tied to user activity?
 * It's tied to post-edit jobs to, for example, prepare the page for the next edit
 * Q: At some point there was a graph on grafana with API usage and statistics, are there plans to bring it back?
 * A: Not sure
 * Why would that be useful?
 * It could be useful as a tool for identifying which jobs could be converted from Action API to Restbase, so as to reduce load across the system
 * data exists ( https://wikitech.wikimedia.org/wiki/Analytics/Data/ApiAction ), might be available on request. The intention is to have some kind of public dashboard eventually.
 * these data could be possibly fetched to grafana (by creating some script etc) if needed. I believe if there is a need for such a workboard, just file a ticket and maybe it will happen some day
 * Q: Authentication/Authorization for frontends
 * A:
 * If you're using JS in the browser, chances are you're already in a session.
 * If not, you can use OAuth 1.0 (extension available) with a server-side proxy
 * OpenID Connect with JWT looks attractive but not implemented (/identify is roughly equivalent, I think - see https://www.mediawiki.org/wiki/OAuth/For_Developers#MediaWiki_Specific_Provisions)
 * Q: How to handle breaking changes to API?
 * Discussion:
 * Make sure to be subscribed to mediawiki-api / mediawiki-api-announce as we notify breaking changes there
 * Deprecation process: https://www.mediawiki.org/wiki/Requests_for_comment/API_roadmap#Deprecation_process (should probably be copied somewhere more "official")
 * Versioning / deprecation policy for REST API: https://www.mediawiki.org/wiki/API_versioning
 * Logging
 * When deprecated code is called, that action triggers the PSR logger
 * Stored in logstash
 * Proposal: use rate limiting to better handle deprecation (force users to register if they use make more than a certain number of requests)
 * Makes development and debugging harder
 * Difficult to make the 1 in a 1000 requests still work
 * People can just reuse the key used by popular existing clients
 * Q: Policy on logging IP addresses
 * A: Log IP addresses to track abuse, but track the minimum possible and purge on a regular basis. Trying to decide whether it's possible to only store hashed IP addresses  (T150545).
 * Q: Performance for RESTBase API
 * A: A responsible client will use the Max-length header to avoiding overloading server (this might have been the action API and maxlag parameter) (it was)
 * Q: Goals of the Action API vs. Wikidata API vs. RESTBase API
 * A: Wikidata API is part of the Action API (apart from WDQS, the SPARQL endpoint), although it does ot always follow the usual conventions.
 * Action items:
 * add more information to the deprecation warnings in the API response
 * add more information to the deprecation warnings in the API response