Jump to content

API Portal/Deprecation

From Wikitech

This page is a work in progress source of information about the 2026 shutdown of the API Portal.

Core API

The Core API provides the ability to search for, fetch, and interact with pages and media files on Wikimedia projects. The Core API uses this URL format: 

https://api.wikimedia.org/core/v1/{project}/{language}/{endpoint}
project
Project name. For example: wikipedia (encyclopedia articles), commons (images, audio, and video), wiktionary (dictionary entries). List all projects.
language
Language code. For example: ar (Arabic), en (English), es (Spanish). List supported languages.

Endpoints

For documentation for parameters and responses, see the MediaWiki REST API reference docs on the REST Sandbox, available on mediawiki.org and any other Wikimedia project.

Search content
GET /core/v1/{project}/{language}/search/page
Search titles
GET /core/v1/{project}/{language}/search/title
Create page
POST /core/v1/{project}/{language}/page
Edit page
PUT /core/v1/{project}/{language}/page/{title}
Get page
GET /core/v1/{project}/{language}/page/{title}/bare
Get page offline
GET /core/v1/{project}/{language}/page/{title}/with_html
Get page source
GET /core/v1/{project}/{language}/page/{title}
Get HTML
GET /core/v1/{project}/{language}/page/{title}/html
Get languages
GET /core/v1/{project}/{language}/page/{title}/links/language
Get files
GET /core/v1/{project}/{language}/page/{title}/links/media
Get file
GET /core/v1/{project}/{language}/file/{title}
Get page history
GET /core/v1/{project}/{language}/page/{title}/history
Get revision stats
GET /core/v1/{project}/{language}/page/{title}/history/counts/{type}
Get revision
GET /core/v1/{project}/{language}/revision/{id}/bare
Compare revisions
GET /core/v1/{project}/{language}/revision/{from}/compare/{to}

Endpoint map

API Method api.wikimedia.org Endpoint Equivalent endpoint
Feed GET /feed/v1/wikipedia/{language}/featured/{YYYY}/{MM}/{DD} {wiki_domain}/api/rest_v1/feed/featured/{YYYY}/{MM}/{DD}

https://en.wikipedia.org/api/rest_v1/feed/featured/2026/01/22

Feed GET /feed/v1/wikipedia/{language}/onthisday/{type}/{MM}/{DD} {wiki_domain}/api/rest_v1/feed/onthisday/{type}/{MM}/{DD}

https://en.wikipedia.org/api/rest_v1/feed/onthisday/all/03/31

Page description GET /core/v1/{project}/{language}/page/{title}/description {wiki_domain}/api/rest_v1/page/summary/{title}

https://en.wikipedia.org/api/rest_v1/page/summary/Dog

Page description PUT /core/v1/{project}/{language}/page/{title}/description ?
Page description DELETE /core/v1/{project}/{language}/page/{title}/description ?
Link recommendation GET /service/linkrecommendation/v1/linkrecommendations/wikipedia/{language}/{title} ?
Link recommendation POST /service/linkrecommendation/v1/linkrecommendations/wikipedia/{language}/{title} ?
Core GET /core/v1/{project}/{language}/search/page {wiki_domain}/w/rest.php/v1/search/page

https://en.wikipedia.org/w/rest.php/v1/search/page?q=dog&limit=1

Core GET /core/v1/{project}/{language}/search/title {wiki_domain}/w/rest.php/v1/search/title

https://en.wikipedia.org/w/rest.php/v1/search/title?q=dog&limit=1

Core POST /core/v1/{project}/{language}/page {wiki_domain}/w/rest.php/v1/page

https://en.wikipedia.org/w/rest.php/v1/page

Core PUT /core/v1/{project}/{language}/page/{title} {wiki_domain}/w/rest.php/v1/page/{title}

https://en.wikipedia.org/w/rest.php/v1/page/Dog

Core GET /core/v1/{project}/{language}/page/{title}/bare {wiki_domain}/w/rest.php/v1/page/{title}/bare

https://en.wikipedia.org/w/rest.php/v1/page/Dog/bare

Core GET /core/v1/{project}/{language}/page/{title}/with_html {wiki_domain}/w/rest.php/v1/page/{title}/with_html

https://en.wikipedia.org/w/rest.php/v1/page/Dog/with_html

Core GET /core/v1/{project}/{language}/page/{title} {wiki_domain}/w/rest.php/v1/page/{title}

https://en.wikipedia.org/w/rest.php/v1/page/Dog

Core GET /core/v1/{project}/{language}/page/{title}/html {wiki_domain}/w/rest.php/v1/page/{title}/html

https://en.wikipedia.org/w/rest.php/v1/page/Dog/html

Core GET /core/v1/{project}/{language}/page/{title}/links/language {wiki_domain}/w/rest.php/v1/page/{title}/links/language

https://en.wikipedia.org/w/rest.php/v1/page/Dog/links/language

Core GET /core/v1/{project}/{language}/page/{title}/links/media {wiki_domain}/w/rest.php/v1/page/{title}/links/media

https://en.wikipedia.org/w/rest.php/v1/page/Dog/links/media

Core GET /core/v1/{project}/{language}/file/{title} {wiki_domain}/w/rest.php/v1/file/{title}

https://commons.wikimedia.org/w/rest.php/v1/file/File:Black_Labrador_Retriever_-_Male_IMG_3323_(cropped).jpg

Core GET /core/v1/{project}/{language}/page/{title}/history {wiki_domain}/w/rest.php/v1/page/{title}/history

https://en.wikipedia.org/w/rest.php/v1/page/Dog/history

Core GET /core/v1/{project}/{language}/page/{title}/history/counts/{type} {wiki_domain}/w/rest.php/v1/page/{title}/history/counts/{type}

https://en.wikipedia.org/w/rest.php/v1/page/Dog/history/counts/bot

Core GET /core/v1/{project}/{language}/revision/{id}/bare {wiki_domain}/w/rest.php/v1/revision/{id}/bare

https://en.wikipedia.org/w/rest.php/v1/revision/1333796539/bare

Core GET /core/v1/{project}/{language}/revision/{from}/compare/{to} {wiki_domain}/w/rest.php/v1/revision/{from}/compare/{to}

https://en.wikipedia.org/w/rest.php/v1/revision/1328607077/compare/1333796539

API keys

API keys created through the API Portal will continue to work and can be managed through Special:OAuthConsumerRegistration on Meta-Wiki. If your API key is not working as expected, leave a comment on Talk:API Portal/Deprecation.

Rate limits

API Portal historical rate limits

Rate limits restrict API calls to a set number of requests per hour based on the type of request. A 429 response code indicates that the applicable rate limit has been exceeded.

These limits only apply to APIs with api.wikimedia.org as the base URL. Rate limits may vary depending on the API; see the individual API docs for the rate limits applicable to each API. For higher rate limits, check out Wikimedia Enterprise.

Anonymous requests
API requests without an access token are limited to 500 requests per hour per IP address.
Personal requests
API requests authenticated using a personal API token (or owner-only consumer) are limited to 5,000 requests per hour.
App-authenticated requests
API requests authenticated using the OAuth 2.0 client credentials flow are limited to 5,000 requests per hour.
User-authenticated requests
API requests authenticated using the OAuth 2.0 authorization code flow are limited to 5,000 requests per hour per user.

Archive

API guidelines (Draft)

This rough draft of guidelines for API maintainers was written in 2021 by SKim (WMF), NNikkhoui (WMF), and BPirkle (WMF) and published at api.wikimedia.org/wiki/Maintainers/API_guidelines, licensed under CC BY-SA 4.0. Links have been modified to work correctly on Wikitech.

API guidelines (Draft)

This document describes guidelines and recommendations for creating APIs at and for use with the Wikimedia Foundation and its associated data, infrastructure, applications, and services.

About the API guidelines

These guidelines attempt to create consistency and encourage secure, efficient, and maintainable APIs. They draw upon previous guidelines and design principles at WMF, as well as common practice across the broader technical community.

These guidelines are not absolute requirements. Not all existing WMF APIs comply with these guidelines. In fact, it is likely that every WMF API differs from these guidelines in some respect. It is equally likely that future WMF APIs will deviate from them. However, any such deviations should be purposeful. In other words, WMF APIs should follow these guidelines unless they have good reason not to.

These guidelines are not comprehensive. There are many aspects to creating real-world APIs, and it is not reasonable for any one document to cover every situation that may arise.

These guidelines are not permanent or unchangeable. If you questions or feedback, please leave a comment on the discussion page.

Terminology

  • API (disambiguation)
    • API (offering): The branded offering for data access in the global context
    • API (SaaS): A web service that provides a capability in the context of Wikimedia
    • API (interface): The client-facing component that interprets HTTP requests
  • API specification (API spec)
    • A technical standard, like OpenAPI 3.0, that defines how to describe an API’s interface in a general, broadly applicable way that is both machine-parsable and human-readable. Other API specification standards include GraphQL and AsyncAPI.
  • API description
    • A file articulating a single API’s interface that fulfills the requirements and expectations of an API specification
  • API documentation
    • The collection of things necessary to convey sufficient meaning so that clients can successfully use the deployed API through the interface. This includes, but is not limited to, the API description.
  • Prototype API
    • A deployed web service with the purpose of being tested as an experiment. These APIs do not have a defined service-level objective (SLO) nor are able to accept public requests higher than a certain threshold rate limit. They have an API status of "experimental" and could change at anytime without notice. +Included in using the API Gateway
  • Production API
    • A deployed web service that has been validated as a prototype and ready for wider use. Has a specified rate limit through the API Gateway
  • End-user
    • The human on their phone pushing buttons on the their respective application
  • Client web app
    • The web application that serves as an interface for the end-user and is the entity making requests to API web service(s)
  • Authorization server
    • For API web services at the Foundation, Meta-Wiki is the entity that handles authorization requests from clients

Design principles

Hosting and infrastructure

This section describes hosting and infrastructure guidelines for WMF-hosted services as well as externally hosted services integrated with WMF infrastructure.

Authentication and authorization

While write requests to api.wikimedia.org (POST, PUT, and DELETE methods) require an OAuth 2.0 token, the API Gateway does not currently support authorizing users and permissions.

Caching

Rate limiting

Long-running tasks

Large datasets

This section describes guidelines for large datasets, both in request and response.

API lifecycle

Design phase

1. Check API catalog*

To ensure we are consistent and DRY, exploring through the existing catalog of APIs will help find reusable patterns or APIs you can extend.

*This currently does not exist yet, please see our List of APIs which is not guaranteed to be up to date

2. Check API guidelines

The evolving set of API guidelines provides the standards and rules we suggest for all API producers to follow.

3. Create API description

Before doing any coding, ensure you have a clear idea and agreement on what your API is supposed to look like. Using the template below will also allow for others to leave comments as well as keep a change log.

4. Generate reference documentation

Based on your API description that you’ve drafted, you can now generate your reference documentation.

5. Get feedback

Whether you’re designing an API for internal operations or for external partners to leverage, you should get feedback from your users before starting any development on your API.

Develop

6. Develop against API description

  • Service Template Node
  • To generate your API OpenAPI specification file as you are developing, you can install the npm package servicelib-node-spec to your project and follow its instructions to first annotate your routes, allowing you to automatically generate your API specification file.

7. Deploy your web service

8. Add API route to the API gateway

We recommend you start off with first adding your API to the staging instance of the API gateway before production.

Deploy

Experimental

Promote

prod vs beta gateway

Evaluate

Sunset

REST API Guidelines

HTTP

Methods

Headers

Status Codes

Naming

We should pick singular vs plural but mention it is just a recommendation

OpenAPI

Explain what it is good for in our infrastructure

Maybe include some lessons from RESTBase and how Kask avoided those issues. See Eric's OpenAPI thoughts (and its talk page) for more.

Service runner / x-amples?

API catalog

Auto-generation via code annotations

Use as communications/contract across teams

Errors

general recommendations on error handling

Logging/monitoring

does this get its own section or can it go under errors? are these related enough to be one section, or should they be separate?

Other API types

Explain that we haven't done that yet, but included this just to make it clear that other API types are not prohibited and we'll fill this in when we get there

Retrieved from "https://wikitech.wikimedia.org/w/index.php?title=API_Portal/Deprecation&oldid=2379912"