Change Details

Request: Production inference services available via the Lift Wing API should generate OpenAPI descriptions ([[https://spec.openapis.org/oas/latest#openapi-description-structure | OADs]]) that comply with the [[ https://spec.openapis.org/oas/latest.html | OpenAPI specification ]]. Currently, Lift Wing API reference documentation is only available as manually-created pages on api.wikimedia.org (the "API Portal"), which is planned for deprecation (T415293): https://api.wikimedia.org/wiki/Lift_Wing_API/Reference. The ML team may need to do a research spike to identify how and whether generating OADs can be accomplished for each of the inference services running on Lift Wing, since the models have varying input requirements and output structures. It's also unclear how KServe versions may impact the ability to auto-generate OAS-compliant OADs. == Timing == We are targeting June 10 to shut down the API Portal, so the Lift Wing API docs need to be published to a new location ideally by June 1 to allow for time to set up redirects. == Project plan == - [x] Create OpenAPI docs for non-revscoring Lift Wing endpoints - [x] Tech Docs review and edits - [ ] Add the OpenAPI docs to the REST Sandbox on Test Wiki T426081 - [ ] Validate the docs on Test Wiki - [ ] Publish the docs to a production wiki (either Wikitech, Meta, or mediawiki.org) - [ ] Create OpenAPI docs for revscoring endpoints - [ ] Tech Docs review and edits - [ ] Redirect API Portal docs to new locations == Project context == As part of the [[https://meta.wikimedia.org/wiki/Wikimedia_Foundation_Annual_Plan/2024-2025/Product_%26_Technology_OKRs#Key_Results | WE5.5 APP KR ]], the MediaWiki Interface and Technical Documentation teams are working with API maintainers to evolve how we build and surface Wikimedia APIs. This includes work bring our API descriptions into alignment with the OpenAPI specification, which enables standardized, generated, and testable API reference documentation. ([[ https://docs.google.com/document/d/15kkWSVKC1WwLzKqqN8jk4hDDPHwA8xZC1nYvRqtDlRE/edit?tab=t.0#heading=h.v0i3vlcj1t17 | strategy doc (Google doc, restricted access) ]] | [[ https://techblog.wikimedia.org/2025/06/12/apis-as-a-product-investing-in-the-current-and-next-generation-of-technical-contributors/ | TechBlog post ]]). We are also working towards deprecating the API portal (T415293), which requires moving API documentation from there to more sustainable locations, and (ideally) for teams to start generating OpenAPI descriptions to produce that API reference documentation (T416586). == Investigations so far == ~~In discussions with @DPogorzelski-WMF , @AikoChou, and @Sucheta-Salgaonkar-WMF, we hypothesized that upgrading the KServe version being used by our current inference services would then enable service owners to just run a simple command to enable the [[ https://kserve.github.io/website/docs/getting-started/swagger-ui | KServe "out of the box" support for OpenAPI ]].~~ * ~~Issue: Upgrading KServe is non-trivial (T380723, T380722, T367048), and we don't actually know for sure if that would enable auto-generation of OpenAPI-compliant API descriptions for Lift Wing inference services. More research is needed (see below for what the tech docs team did so far to research this.)~~ Update: Upgrading KServe is unrelated to this work per T419455#11893320 @KBach did some initial exploration and tried to generate an OpenAPI description for the Revscoring goodfaith model, but was not able to successfully do that because of: # Unclear/incomplete [[ https://kserve.github.io/website/docs/getting-started/swagger-ui | KServe documentation about "out of the box" support for OpenAPI ]] # Variations in response structure depending on request parameters make the API potentially incompatible with OpenAPI description format. See full notes in [[ https://docs.google.com/document/d/1M6-Vlp3dty3Rx7SR_RLSTzAYBKadYCkL1Wac-83OQZY/edit?tab=t.0#heading=h.y3kkrp12x67d | Google doc ]]. The Link Recommendation API is an example of an ML model-based service (not running on Lift Wing infra) that complies with OpenAPI: see T415312 and https://gerrit.wikimedia.org/r/plugins/gitiles/research/mwaddlink/+/refs/heads/main/swagger/linkrecommendations.yml

Request: Production inference services available via the Lift Wing API should generate OpenAPI descriptions ([[https://spec.openapis.org/oas/latest#openapi-description-structure | OADs]]) that comply with the [[ https://spec.openapis.org/oas/latest.html | OpenAPI specification ]]. Currently, Lift Wing API reference documentation is only available as manually-created pages on api.wikimedia.org (the "API Portal"), which is planned for deprecation (T415293): https://api.wikimedia.org/wiki/Lift_Wing_API/Reference. The ML team may need to do a research spike to identify how and whether generating OADs can be accomplished for each of the inference services running on Lift Wing, since the models have varying input requirements and output structures. It's also unclear how KServe versions may impact the ability to auto-generate OAS-compliant OADs. == Timing == We are targeting June 10 to shut down the API Portal, so the Lift Wing API docs need to be published to a new location ideally by June 1 to allow for time to set up redirects. == Project plan == - [x] Create OpenAPI docs for non-revscoring Lift Wing endpoints - [x] Tech Docs review and edits - [x] Add the OpenAPI docs to the REST Sandbox on Test Wiki T426081 - [x] Validate the docs on Test Wiki - [x] Publish the docs to a production wiki (either Wikitech, Meta, and mediawiki.org) - [x] Create OpenAPI docs for revscoring endpoints - [x] Tech Docs review and edits - [x] Redirect API Portal docs to new locations - [ ] Discuss maintenance strategy for OpenAPI docs for translation endpoint == Project context == As part of the [[https://meta.wikimedia.org/wiki/Wikimedia_Foundation_Annual_Plan/2024-2025/Product_%26_Technology_OKRs#Key_Results | WE5.5 APP KR ]], the MediaWiki Interface and Technical Documentation teams are working with API maintainers to evolve how we build and surface Wikimedia APIs. This includes work bring our API descriptions into alignment with the OpenAPI specification, which enables standardized, generated, and testable API reference documentation. ([[ https://docs.google.com/document/d/15kkWSVKC1WwLzKqqN8jk4hDDPHwA8xZC1nYvRqtDlRE/edit?tab=t.0#heading=h.v0i3vlcj1t17 | strategy doc (Google doc, restricted access) ]] | [[ https://techblog.wikimedia.org/2025/06/12/apis-as-a-product-investing-in-the-current-and-next-generation-of-technical-contributors/ | TechBlog post ]]). We are also working towards deprecating the API portal (T415293), which requires moving API documentation from there to more sustainable locations, and (ideally) for teams to start generating OpenAPI descriptions to produce that API reference documentation (T416586). == Investigations so far == ~~In discussions with @DPogorzelski-WMF , @AikoChou, and @Sucheta-Salgaonkar-WMF, we hypothesized that upgrading the KServe version being used by our current inference services would then enable service owners to just run a simple command to enable the [[ https://kserve.github.io/website/docs/getting-started/swagger-ui | KServe "out of the box" support for OpenAPI ]].~~ * ~~Issue: Upgrading KServe is non-trivial (T380723, T380722, T367048), and we don't actually know for sure if that would enable auto-generation of OpenAPI-compliant API descriptions for Lift Wing inference services. More research is needed (see below for what the tech docs team did so far to research this.)~~ Update: Upgrading KServe is unrelated to this work per T419455#11893320 @KBach did some initial exploration and tried to generate an OpenAPI description for the Revscoring goodfaith model, but was not able to successfully do that because of: # Unclear/incomplete [[ https://kserve.github.io/website/docs/getting-started/swagger-ui | KServe documentation about "out of the box" support for OpenAPI ]] # Variations in response structure depending on request parameters make the API potentially incompatible with OpenAPI description format. See full notes in [[ https://docs.google.com/document/d/1M6-Vlp3dty3Rx7SR_RLSTzAYBKadYCkL1Wac-83OQZY/edit?tab=t.0#heading=h.y3kkrp12x67d | Google doc ]]. The Link Recommendation API is an example of an ML model-based service (not running on Lift Wing infra) that complies with OpenAPI: see T415312 and https://gerrit.wikimedia.org/r/plugins/gitiles/research/mwaddlink/+/refs/heads/main/swagger/linkrecommendations.yml

Request: Production inference services available via the Lift Wing API should generate OpenAPI descriptions ([[https://spec.openapis.org/oas/latest#openapi-description-structure | OADs]]) that comply with the [[ https://spec.openapis.org/oas/latest.html | OpenAPI specification ]]. Currently, Lift Wing API reference documentation is only available as manually-created pages on api.wikimedia.org (the "API Portal"), which is planned for deprecation (T415293): https://api.wikimedia.org/wiki/Lift_Wing_API/Reference. The ML team may need to do a research spike to identify how and whether generating OADs can be accomplished for each of the inference services running on Lift Wing, since the models have varying input requirements and output structures. It's also unclear how KServe versions may impact the ability to auto-generate OAS-compliant OADs. == Timing == We are targeting June 10 to shut down the API Portal, so the Lift Wing API docs need to be published to a new location ideally by June 1 to allow for time to set up redirects. == Project plan == - [x] Create OpenAPI docs for non-revscoring Lift Wing endpoints - [x] Tech Docs review and edits - [ - [x] Add the OpenAPI docs to the REST Sandbox on Test Wiki T426081 - [ - [x] Validate the docs on Test Wiki - [ - [x] Publish the docs to a production wiki (either Wikitech, Meta, orand mediawiki.org) - [ - [x] Create OpenAPI docs for revscoring endpoints - [ - [x] Tech Docs review and edits - [x] Redirect API Portal docs to new locations - [ ] Redirect API PortalDiscuss maintenance strategy for OpenAPI docs to new locationsfor translation endpoint == Project context == As part of the [[https://meta.wikimedia.org/wiki/Wikimedia_Foundation_Annual_Plan/2024-2025/Product_%26_Technology_OKRs#Key_Results | WE5.5 APP KR ]], the MediaWiki Interface and Technical Documentation teams are working with API maintainers to evolve how we build and surface Wikimedia APIs. This includes work bring our API descriptions into alignment with the OpenAPI specification, which enables standardized, generated, and testable API reference documentation. ([[ https://docs.google.com/document/d/15kkWSVKC1WwLzKqqN8jk4hDDPHwA8xZC1nYvRqtDlRE/edit?tab=t.0#heading=h.v0i3vlcj1t17 | strategy doc (Google doc, restricted access) ]] | [[ https://techblog.wikimedia.org/2025/06/12/apis-as-a-product-investing-in-the-current-and-next-generation-of-technical-contributors/ | TechBlog post ]]). We are also working towards deprecating the API portal (T415293), which requires moving API documentation from there to more sustainable locations, and (ideally) for teams to start generating OpenAPI descriptions to produce that API reference documentation (T416586). == Investigations so far == ~~In discussions with @DPogorzelski-WMF , @AikoChou, and @Sucheta-Salgaonkar-WMF, we hypothesized that upgrading the KServe version being used by our current inference services would then enable service owners to just run a simple command to enable the [[ https://kserve.github.io/website/docs/getting-started/swagger-ui | KServe "out of the box" support for OpenAPI ]].~~ * ~~Issue: Upgrading KServe is non-trivial (T380723, T380722, T367048), and we don't actually know for sure if that would enable auto-generation of OpenAPI-compliant API descriptions for Lift Wing inference services. More research is needed (see below for what the tech docs team did so far to research this.)~~ Update: Upgrading KServe is unrelated to this work per T419455#11893320 @KBach did some initial exploration and tried to generate an OpenAPI description for the Revscoring goodfaith model, but was not able to successfully do that because of: # Unclear/incomplete [[ https://kserve.github.io/website/docs/getting-started/swagger-ui | KServe documentation about "out of the box" support for OpenAPI ]] # Variations in response structure depending on request parameters make the API potentially incompatible with OpenAPI description format. See full notes in [[ https://docs.google.com/document/d/1M6-Vlp3dty3Rx7SR_RLSTzAYBKadYCkL1Wac-83OQZY/edit?tab=t.0#heading=h.y3kkrp12x67d | Google doc ]]. The Link Recommendation API is an example of an ML model-based service (not running on Lift Wing infra) that complies with OpenAPI: see T415312 and https://gerrit.wikimedia.org/r/plugins/gitiles/research/mwaddlink/+/refs/heads/main/swagger/linkrecommendations.yml