Hypothesis text:

If we create new mechanisms that allow API users to safely engage with proposed endpoints before they are officially released, we will be able to mitigate risks related to introducing new API versions and foster more meaningful engagement with the developer community.

Milestones:

• Research spike to explore alignment with event stream entity models so that they may be reused across integration types.
• Improve API monitoring & alarms.
• Versioning & deprecation processes (including preview/experimental endpoints)
  • [Stretch? – previously contentious] Audience/usage specification (eg: beta, internal/private)
    • Alternatively: Only scope to ‘Beta’ opt-in use cases.
    • Alternative alternative: ‘Beta’ is designated as /v0?
• Propose and align on API response shapes using MW REST reference implementations :
  • Error codes and message structure
  • Pagination (NOTE: MW REST API currently has no endpoints that expect/require pagination; page history is the closest, with revision skip values)
    • New page history endpoint as candidate
• Implement at least ~10 endpoints from the MediaWiki REST API to reflect the new standards.
  • Marked as experimental (or beta) & only available on testwiki
  • Feature flagged within the 1.44 release, to prevent accidental adoption
  • Route new endpoints through [REST Gateway] as the centralized standard gateway
• Invite internal and community developers to test the new API formats and provide feedback on the experience.
  • Iterate the design as needed
• [Stretch] Propose and align on module definitions, including roadmap of endpoints