5.2.2c: [Reroute API Portal Endpoints] If we reroute all APIs currently going through the API Gateway through the common gateway, we will be able to fully deprecate the historic API Gateway and ensure consistency for all community facing Wikimedia HTTP/web APIs.

Background

Our KR focuses on migrating existing APIs to utilize common infrastructure, so that we may start driving commonalities across Wikimedia APIs and make it easier to monitor, maintain, and deliver API capabilities. The most critical piece of that infrastructure is introducing a universal API Gateway. Utilizing a common API gateway to serve, monitor, and control API access paves the way for more complex program needs, such as standardizing rate limits and authentication mechanisms. This gateway will take advantage of the existing API management gateway known internally as the REST gateway.

Problem statement

The APIs currently documented in the API Portal are routed through a bespoke API Gateway. The API Gateway configuration is complex, as it needs to support a unique URL pattern with heavy custom routing logic. Additionally, it is currently one of the only places within the Foundation that clearly documents and enforces API rate limits.

Impacted users
If done correctly, this work should have no impact on API users. Instead, it will provide benefits to API authors and owners by creating a centralized location to view API traffic and performance. Additionally, as we move towards standardizing API controls such as rate limiting and concurrency, API managers will have a single point to observe and enforce.

Scope

• Duplicate API Gateway configuration onto the common REST Gateway.
• Configure endpoint specific logic that allows for higher limits on Lift Wing endpoints, so that functionality is not lost during migration.
• Deprecate and fully sunset the historic API Gateway.

Out of Scope

• This work does not include deprecating the API Portal as a documentation solution; that will be covered in a separate hypothesis.
• Although there are intentions to deprecate the MediaWiki Core API, that is not considered in scope at this time. Configuration and support will be carried over in entirety for now, with the intention to strip it out after going through a full deprecation cycle (and likely not until the REST API v2 is announced).

Expected Outcomes

The only Foundation APIs considered 'in scope' for API Platform work are those documented in the API Portal. Once they are routed through the common gateway, we will have 100% coverage for all existing APIs going through a singular, common API Gateway. This means that we will have a unified point of control for policy enforcement, traffic monitoring, and utilization patterns for all Wikimedia APIs.

Known risks & limitations

• The API Gateway has a significant amount of custom configuration that will need to be carried over to the new Gateway.
  • Mitigation: Both instances are powered through Envoy, meaning the actual migration of the settings should be straightforward and low risk. We will also strip out much of the custom logic with the intended deprecation of the MediaWiki Core APIs.
• As part of the rerouting, we are intentionally leaving some patterns behind. For example, we will no longer allow rate limit overrides through the JWT; instead, the new Gateway exclusively applies limits based on user-classes. This may cause some edge case impacts.
  • Mitigation: We will audit existing JWT utilization to determine how frequently and what API users are currently granted JWT based overrides. We can engage with those users directly and/or ensure they are assigned to a comparable user-class.

Related Work
This is the final step of the rerouting work covered by the other WE 5.2.2 hypotheses.
There is related work for migrating documentation out of the API Portal so we can similarly deprecate that as a bespoke documentation solution.

Dependencies
None.

Next steps

Deprecate the API Portal and MediaWiki Core APIs!

Deadline

We expect this work to be completed by the end of Q3 (March 27, 2025)