Change Details

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. [x] 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 * 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

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. [x] 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 ]]) [X] 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

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. [x] 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 ]]) [X] MW PMs agree (approvaled by @Bmueller pending) == 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