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, Routing for the `/api/rest_v1/` prefix should remain intactthe `$wgRestPath` setting can be changed to `/api/`, since it happens beforeanalogous to `$wgArticlePath`. But that's outside of the request reaches Apache app servers (in ATS?)scoep iof this ticket, and needs to be announced widely.
Once the rewrite rule is in place, the `$wgRestPath` setting can be changed to `/api/`, analogous to `$wgArticlePath`.
== 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 agreesx] SRE agrees (per meeting with @MShilova_WMF, @akosiaris, @Vgutierrez, and @FJoseph-WMF on May 22, see [[ https://docs.google.com/document/d/1JeTSiPCjqYLcLCaYSXI2Uf6kK7V6_XCT461J-XspVBw/edit#heading=h.qpuvbjacexx1 | notes ]])
[] MW PMs agree (approval by @Bmueller pending)
== References ==
* Arc42: https://docs.google.com/document/d/1ZrVTRWoG2W4KzZLFAz161hAQiqsrXCJcAAnYhmU5_2k
* Slide deck: https://docs.google.com/presentation/d/173WciDCIcdBvMFnq1scVqCG02Hk_wtiya9zYFiqDRQU