I am new to MediaWiki's [[ https://www.mediawiki.org/wiki/API:Main_page | 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).
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 flexability and/or cacheability.
It also would help avoid [[ http://bikeshed.org/ | bikeshedding ]].
* [[ http://jsonapi.org/ | JSON API ]] ([[ http://jsonapi.org/format/ | spec ]], [[ http://jsonapi.org/implementations/ | implementations ]]) does not allow complex queries, but the responses are highly cacheable.
* T181257 allows complex queries, but is not highly catchable.
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.