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.

Wikimedia REST APIs can be either per-domain, or central. Contral endpoints are access on api.wikimedia.org, while per-domain APIs are exposed by each wiki separately.

$\|An API SHOULD be exposed using the central 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. \|$

$\|APIs accessible from outside the Wikimedia network SHOULD use the following URL patterns: \|
 * (central)
 * (per domain)$

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

Component
The  part of the URL represents a unit of deployment.

$\|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. They are collectively understood as "one API".\|$ $\|All 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.\|$

Components can be understood as conceptual domain models [TBD: link DDD]. 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.

$\|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 generally have a separate prefix. They may share a prefix with another service or extension only if both are maintained by the same team.\|$

If we end up having many ugly sounding, non-obvious component names, this indicates that something is wrong with the team structure. In that case, both the teams and the APIs should be re-structured, using the mechanisms described in the sections on Versioning and Deprecation.

$\|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.\|$

Gateway
The  part of the URL identifies the gateway to be used to access the API.

The idea is that it may be useful to be able to provide dedicated resources for certain operations, clients, or purposes. Including this information in the URL makes it easy to route requests to the correct place early.

$\|APIs SHOULD be exposed through the generic gateway called, unless there is a specific reason to expose it through additional or different gateways.\|$

There may be other gateways, for instance  is in   https://api.enterprise.wikimedia.com/v2/snapshots.

$\|The names of gatways SHOULD contain the word  as a prefix or suffix, to avoid collisions with components as well as paths and subdomains used for other purposes.\|$

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 consist of characters [TBD: range, RFC, etc]\|$$\|The following names are reserved: \|
 * : used as MediaWiki's script path.
 * : used as MediaWiki's article path.
 * : reserved for testing. [TBD]
 * : reserved for testing. [TBD]
 * : reserved for operational use. [TBD]$

TBD: Note that gateway names must end in "api", and component names must not end in "api", to avoid confusion and conflits on the  domain.[TBD: more about that confusion!]

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