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.

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

NORM: APIs accessible from outside the Wikimedia network SHOULD use the following URL patterns:


 * (central)
 * (per domain)

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

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

NORM: All API endpoints that share a component prefix SHOULD be maintained by the same team. They are collectively understood as "one API".

NORM: All API endpoints that share a component prefix SHOULD always be deployed and updated together.

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

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

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

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

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

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.

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

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
NORM: 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 followed by a slash ("/").

NORM: Gateway and component names must consist of characters [TBD: range, RFC, etc]

NORM: Gateway and component names SHOULD avoid the use of characters that may carry meaning as part of a URL, such as dots (".") and slashes ("/"). Hyphens ("-") should also be avoided to prevent collitions with variant paths. Gateway names MUST NOT contain spaces, hashes ('#'), plus signs ('+'), question marks, or ampersands ('+')

NORM: 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]

NORM: Gateway names must not contain hyphens ("-"). This is to avoid confusion with variant paths. [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!]

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.