User:DKinzler (WMF)/API URL Guidelines

This document provides guidelines for the URLs under which APIs are exposed on Wikimedia sites. It is designed primarily for the use with REST APIs, but may be applied to other types of APIs as well. It does not apply to the MediaWiki action API.

The Examples section below provides information on how this applies to existing and new APIs.

Gateway Identifiers
There should rarely be a need to introduce a new gateway. If a new gateway is to be introduced, the names of the gatway SHOULD contain the word  as a prefix or suffix, to avoid collisions with components as well as paths and subdomains used for other purposes. See also Constraints on Names below.

Component Names
The following additional norms apply to component APIs:

Constraints on Names
The following names are reserved:

The MediaWiki Action API
/w/api.php

The MediaWiki REST entry point
/w/rest.php

The API Portal Wiki
api.wikimedia.org/api

Wikis with language variant paths
https://sr.wikipedia.org/sr-el/%D0%9A%D0%BE%D1%81%D0%BC%D0%BE%D0%BD%D0%B0%D1%83%D1%82

Examples
EXAMPLE:

The liftwing API is an example of a central API. Consider the following URL:

https://api.wikimedia.org/service/lw/inference/v1/models/enwiki-articlequality:predict

Here, the gateway is, the component is  , and the path is.

EXAMPLE:

The parsoid API is an example of a per-wiki API:

https://en.wikipedia.org/api/rest_v1/page/html/Earth

Here, the gateway is, the component is  , and the path is.

TBD: BAD EXAMPLE of per domain API on api.wikimedia.org

TBD: EXAMPLE of a per-wiki API for the wiki on api.wikimedia.org

TBD: BAD EXAMPLE: https://api.enterprise.wikimedia.com/v2/snapshots.

Attic
APIs may be Wikimedia-specific or portable (that is, defined by a component that can easily be installed and run by a third party). All centralized endpoints are Wikimedia specific.