RESTBase Deprecation: Migration Guide to MediaWiki REST API for Developers

For years, RESTBase was the backbone for anyone building bots or tools that needed clean HTML from Wikipedia. It sat between the raw MediaWiki database and your application, converting wikitext into structured HTML on the fly. But as of mid-2026, that convenience layer is officially being retired. If you are still relying on /page/html endpoints via RESTBase, your integration will soon break. The good news? The replacement isn't a downgrade-it's actually faster and more stable.

The core shift is moving from a specialized proxy service to the native MediaWiki REST API. This new standard exposes the same data but directly from the source, eliminating an extra hop in the network request. For developers, this means fewer points of failure and better performance metrics. However, it also requires updating your code to handle slightly different response structures and authentication methods.

Why RESTBase Is Going Away

RESTBase was originally designed to provide a RESTful interface to MediaWiki content, primarily serving HTML generated by Parsoid. While it served its purpose well during its early years, maintaining a separate infrastructure stack became costly and complex. The Wikimedia Foundation decided that the benefits of having a dedicated REST gateway no longer outweighed the maintenance overhead, especially since the core MediaWiki software has matured significantly in its ability to serve REST requests natively.

From a technical standpoint, RESTBase added latency. Every request had to travel from your client to the RESTBase server, which then queried the MediaWiki instance, processed the content through Parsoid, and sent it back. Now, with the direct MediaWiki REST API, the path is shorter. You query the MediaWiki instance directly, which handles the serialization. This reduction in hops typically results in a 15-20% decrease in average response time for large pages.

Key Differences Between RESTBase and the New API

Before you start changing code, it helps to understand what is actually different under the hood. The most significant change is the endpoint structure and how metadata is handled. In RESTBase, you might have requested /v1/page/html/{title}. In the new system, the endpoints are organized differently, often grouped under /api/rest_v1/page/.

One subtle but critical difference is how revisions are handled. RESTBase allowed you to easily fetch the HTML for a specific revision ID. The new API supports this too, but you must explicitly pass the revision parameter in the URL path or query string, ensuring that the cache keys are precise. If you were relying on default caching behaviors in RESTBase, you need to be more explicit now about which version of the page you want.

Step-by-Step Migration Process

Migrating doesn't have to be a massive rewrite. Most developers can transition their code in under an hour if they follow a systematic approach. Here is how I recommend handling the switch:

1. Audit Your Endpoints: Search your codebase for any strings containing restbase.wikimedia.org or similar subdomains. List every unique URL pattern you use.
2. Update Base URLs: Replace the base domain with the appropriate MediaWiki REST endpoint. For English Wikipedia, this is typically en.wikipedia.org/api/rest_v1/. Note that the path structure changes slightly; you may need to adjust the route parameters.
3. Adjust Headers: Ensure your HTTP client sends the correct Accept header. If you want HTML, send Accept: text/html. If you want structured data, send Accept: application/json. The server will respond accordingly.
4. Handle Authentication: If your bot uses OAuth or API tokens, ensure they are valid for the new API scope. Some older tokens issued specifically for RESTBase might need refreshing to work with the core MediaWiki REST interface.
5. Test Error States: Run your bot against a test environment or a small subset of pages. Check how the new API handles missing pages, protected edits, and rate limits. The error JSON structure is cleaner now, but your parsing logic might need minor tweaks.

Don't forget to update your logging. Since the response times are different, your timeout settings might need adjustment. A request that took 800ms on RESTBase might take 600ms on the new API, so if you have strict timeouts set at 700ms, you're safe. But if you had them set very tightly, give yourself some breathing room.

Handling Rate Limits and Performance

Performance is where the new API really shines, but only if you manage your requests wisely. The old RESTBase system used a global rate limit per IP address, which could be problematic if multiple users shared an IP (like in corporate environments). The new system uses a more granular approach based on user agents and API tokens.

To maximize throughput, consider implementing exponential backoff in your retry logic. If you hit a 429 status code (Too Many Requests), wait for the duration specified in the Retry-After header before trying again. This is much more reliable than guessing how long to pause. Also, leverage conditional requests using the If-None-Match header with ETags. If the page hasn't changed, the server will return a 304 Not Modified response, saving bandwidth and processing power.

For high-volume bots, batching requests can help. While the REST API doesn't support multi-page fetching in a single call like the legacy Action API did, you can parallelize requests using asynchronous HTTP clients. Just be mindful of the total number of concurrent connections to avoid overwhelming the server. A sweet spot for most bots is 5-10 concurrent requests per user agent.

Common Pitfalls to Avoid

Even with a straightforward migration, there are a few traps that can trip up developers who aren't paying close attention. One common issue is assuming that the HTML output is identical byte-for-byte. While the content is the same, the class names and attribute ordering in the HTML might differ slightly due to updates in Parsoid versions. If your scraper relies on specific CSS selectors, test them thoroughly against the new output.

Another pitfall is ignoring the Cache-Control headers. The new API provides more detailed caching instructions. If you ignore these and cache responses indefinitely, you might end up serving stale data to your users. Respect the max-age directives provided by the server. For dynamic content, consider setting a shorter local cache TTL to balance freshness and performance.

Finally, don't neglect monitoring. Set up alerts for increased error rates or latency spikes after the migration. Sometimes, subtle changes in how the API handles edge cases (like redirects or disambiguation pages) can cause silent failures in your pipeline. Keeping an eye on your logs for the first week post-migration will save you headaches later.

Frequently Asked Questions