Currently, we are exposing REST APIs for each wiki from two pathes:
- /api/rest_v1/ for APIs handled by standalone services (restbase and otherwise).
- /w/rest.php/ for APIs handled by MediaWiki (core and extensions)
We should consolidate the two, so clients do not have to be aware how an API is implemented, and we are free to change how it is implemented without breaking clients. Also, shared prefix for all REST APIsmakes configuration of the edge caches more straight forward.
Proposal
This can be achived by introducing a rewrite rule into the Apache config that maps /api/ to /w/rest.php exactly in the same way we map /wiki/ to /w/index.php.
In the ATS layer, we need a rule that will send traffic for /api/ to MW app servers in the API cluster. However, traffic for the
/api/rest_v1/ prefix still needs to be sent to RESTbase / REST Gateway.
Once the routing rules are in place, the $wgRestPath setting can be changed to /api/, analogous to $wgArticlePath. But that's outside of the scoep iof this ticket, and needs to be announced widely.
Impact
APIs that are currently exposed under /w/rest.php will also become availabe under /api/, for example:
- /w/rest.php/v1/page/{title}/html will become available under /api/v1/page/{title}/html.
- /w/rest.php/oauth2/authorize will become available under /api/oauth2/authorize.
- /w/rest.php/ipinfo/v0/revision/{id} will become available under /api/ipinfo/v0/revision/{id}.
Note that we will have /api/rest_v1/ prefix side by side with core's /api/v1/ prefix, which is slightly confusing. The idea is to move APIs out of both generic prefixes over time:
- With the sunsetting of RESTbase, we can move APIs out of the /api/rest_v1/ prefix to dedicated prefixes, e.g. /api/citation.v1/ instead of /api/rest_v1/data/citation/.
- With the introducion of modules into the MediaWiki REST framework, we can move APIs out of the /api/v1/ prefix to dedicated prefixes, e.g. /api/content.v1/page/ instead of /api/v1/page/.
Future
If we have a need to route different paths under /api/ to different services (beyond rest_v1) , we can route all requests for the /api/ prefix through an API gateway. This would also provide unified intrumentation for all REST endpoints.
Aproval
This idea has been floated and discussed for a while. This task should be used to discuss any remaining issuesd, and document consensus.
- SRE agrees (per meeting with @MShilova_WMF, @akosiaris, @Vgutierrez, and @FJoseph-WMF on May 22, see notes)
- MW PMs agree (approved by @Bmueller)
References
- Arc42: https://docs.google.com/document/d/1ZrVTRWoG2W4KzZLFAz161hAQiqsrXCJcAAnYhmU5_2k
- Design document: https://docs.google.com/document/d/1cKaaAzhd6WQPqOrvT_Fg5TKt1AaIh_ADt6ocZUoi3IQ/edit#bookmark=id.64shbivaslv7
- Slide deck: https://docs.google.com/presentation/d/173WciDCIcdBvMFnq1scVqCG02Hk_wtiya9zYFiqDRQU