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 ideally identifies the domain of the API. However, it is more important that reflect organizational reality: all endpoints under a given component should be owned by a single team, just like all code in a software component should be owned by a single team. If two teams are running endpoints that are conceptually similar, they should still use different  prefixes. This may even mean using the team name as the component prefix.

The reason for insisting that component prefixes align with team boundaries is that components are units of versioning, and teams must have autonomy over the life cycle of endpoints they run.

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.

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.

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.

For instance, there may be other gateways, e.g. an "enterprise-api" gateway reserved for high volume access requiring special API keys.

Path
TBD

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

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.