As discussed in {T248553} it appears the 'media' endpoint decommission resulted in breakage.
This is a task to represent work to do a simple postmortem and then review and enhance the the service lifecycle process.
**BACKGROUND**
The original design of the Page Content Service ca. 2017 called for several API endpoints for retrieving page-related data. The goal of the project was to replace the legacy /page/mobile-sections endpoints with a more robust and fully-featured API suitable for adoption by a wide variety of clients. The planned PCS endpoints included /page/summary, which provided a summary of the most important page metadata and was used for supporting Page Previews; /page/mobile-html for providing pre-formatted page HTML content suitable for native app clients; endpoints for page-specific scripts and styles; and several supporting endpoints for retriving JSON-structured page metadata: /page/media for providing data about the media items used on a page, /page/references for providing structured reference content, and /page/metadata for providing miscellaneous metadata not already included elsewhere. In late 2017 and early 2018 most of the PCS endpoints were publicly launched, with their stability listed as experimental in the Wikimedia REST API documentation. The mobile-html endpoint proved to be a more complex undertaking than the others, and was not launched until 2019.
In mid- to late 2019, as the app teams began the work of adopting Page Content Service endpoints, the service endpoints began to evolve for various reasons from the original 2017 plan. It came to light that /page/media was impossible to invalidate correctly from cache without infrastructure support beyond the scope of the PCS project, so it was superseded by a more narrowly scoped /page/media-list endpoint. The page references were incorporated into the mobile-html content, rendering the /page/references endpoint unnecessary, and the various items included in /page/metadata were either incorporated into other endpoints or declared unnecessary. Hence, PI and CPT planned to remove the experimental /page/media, /page/references, and /page/metadata endpoints from the public REST API at a convenient time.
Meanwhile, unbeknownst to PI, the Inuka team began consuming the /page/media endpoint in the new KaiOS app.
In March 2020, PI and CPT removed the /page/media, /page/references, and /page/metadata endpoints from the REST API, declining to announce the change since the endpoints were experimental. Unfortunately, removing /page/media broke the prototype KaiOS app. This created additional work for the Inuka team but did not affect end users since the KaiOS app has not yet launched.
**ISSUES PRESENTED**
- **Visibility of endpoint stability:** The stability of an API endpoint should be readily apparent and easy to find. Developers consuming an experimental, unstable, or beta endpoint should be aware that they are doing so.
- **Communication:** More communication between the developer teams would likely have prevented any mistaken assumptions about the stability level or future of the various PCS endpoints. Of course, developers are not required to ask permission before consuming a public API, but discussing plans with the API's maintainers is advisable. Likewise, it is advisable for API maintainers to publicly advertise changes like removing a long-standing public API endpoint, even if that endpoint is advertised as experimental.
**RECOMMENDATIONS**
Product Infrastructure should take the following actions to prevent future incidents:
- ** Improve API stability documentation:** The [[ https://www.mediawiki.org/wiki/Page_Content_Service | Page Content Service ]] wiki page should advertise the stability of the public API endpoints. Where the stability is anything less than stable, the stability level should be featured prominently.
- **Announce all breaking API changes:** As a courtesy, all breaking API changes should be announced on wikitech-l at least two weeks in advance, even if the affected endpoints are marked experimental.