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.

Meaning of URL Parts
The URLs of API endpoints accessible from outside the Wikimedia network SHOULD be constructed from three parts: The gateway identifyer, the component name, and the endpoint path. This document provides guidelines for each of theser parts.

URL Patterns
Wikimedia REST APIs can be either per-wiki, or centralized [TBD: better term?]. Contralized endpoints are accessed using a single domain (one per gateway, see below), while per-wiki APIs are exposed on each wiki's domain separately.


 * centralized URL pattern:
 * per-wiki URL pattern:

All APIs accessible from outside the Wikimedia network SHOULD use one of these two patterns. An API SHOULD be exposed using the centralized pattern if it provides functionality the combines the content of multiple wikis into a single response. In contrast, APIs that operate on the content of a specific wiki should use a per-wiki URL.

Gateway Identifiers
The  part of the URL identifies the gateway to be used to access the API. Most APIs SHOULD be exposed through the generic gateway called, unless there is a specific reason to expose it through additional or different gateways.

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.TBD: dedicated gateways (songle component)

TBD: restricted gateways (not stable for public use, even if they expose apis that are). Use wmf-xyp instead of apo-xyz?

Component Names
The  part of the URL represents a logical grouping of endpoints which together consitute the API of a functional component.

Component APIs act as units of versioning and units of deployment: all endpoints under a component prefix SHOULD always updated together, to ensure consistency between them. Because of this, all endpoints under a component prefix SHOULD be maintained by the same team. This provides teams with autonomy over the lifecycle of the APIs they own.

To allow component APIs to evolve without causing disruption to clients, the component name SHOULD contain a version number or stability indicator (see Versioning). The preferred way to include this information is by deviding the name into two parts separated by a slash ("-"). The first part being the component name, the second part is the version:  [TBD: which separator is preferred? We seeom to be using "/" mostly]. Using other separators like slash or underscore is acceptable but discouraged. Examples include  and. See also Constraints on Names below.

The following additional norms apply to component APIs:


 * The component's root URL (with the  part empty) SHOULD return documentation about the API it exposes.
 * MediaWiki extensions and stand-alone backend services SHOULD each have a separate prefix. They may share a prefix with another service or extension only if both are maintained by the same team.
 * The names of components MUST NOT contain the word  as a prefix or suffix separated with a non-alphanumeric character such as a dot (".") or slash ("/") or hyphen ("-"). This avoids collisions with gateway identifyers. See also Constraints on Names below.

TBD: unique name across all gateways (?)

TBD: whether an API is stable should be obvious from the URL!

Endpoint Paths
TBD: summary of User:DKinzler_(WMF)/REST_Entity_Path_Guidelines

TBD: short blurp about RPC APIs.

TBD: Note that centralized endpoints should not include a  parameter in the path. If the resourced accessed by an API is specific to a site, it should be accessed using the domain of that site, not using an endpoint on. This ensure that we consistently apply per-wiki user group memberships and rate limits.

Constraints on Names
The names of components or gateways MUST NOT be one of the reserved names, and the name of components or gateways MUST NOT start with a reserved name separated by a non-slphanumeric character such as slash ("/") or dot (".") or hyphen ("-").

Gateway and component names MUST match the following ABNF rule, per RFC 2234:

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.