Wikimedia Developer Summit/2017/Action API
Appearance
- 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
- Action API: https://www.mediawiki.org/wiki/API:Main_page
- 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
- There are gradual changes towards API-driven frontend
- 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
- Why would that be useful?
- 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