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
Wikimedia REST APIs can be either per-domain, or centralized [TBD: better term?]. Contralized endpoints are accessed on, while per-domain APIs are exposed by each wiki's domain separately.


 * centralized:
 * per-domain:

All APIs accessible from outside the Wikimedia network SHOULD use one of the 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-domain URL.

Component
The  part of the URL represents a logical grouping of endpoints which together consitute the API of a component. Components can be understood as conceptual domain models. However, it is more important that they reflect organizational reality: component prefixes should align with team boundaries to ensure cohesion and consistency, providing teams with autonomy over the life cycle of the endpoints they maintain.

The following norms apply to component APIs:
 * The component name SHOULD contain a version and stability identifyer (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 or stability indicator: . Using a hyphen or underscore to separate the version is also acceptable, as in  or  .
 * All API endpoints that share a component prefix SHOULD be maintained by the same team.
 * API endpoints that share a component prefix SHOULD always be deployed and updated together.
 * The component's root URL (with the  part empty) SHOULD return documentation about the API it exposes.
 * If two teams are running endpoints that are conceptually similar, they SHOULD still use different component. This may even mean using the team name as the component prefix.
 * 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 names. See also Constraints on Names below.

Gateway
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.

Path
TBD: summary of User:DKinzler_(WMF)/REST_Entity_Path_Guidelines

TBD: short blurp about RPC APIs.

TBD: Note that central 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 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-domain 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-domain 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 central endpoints are Wikimedia specific.