User:DKinzler (WMF)/API URL Guidelines

This document provides guidelines for the URLs under which APIs are exposed on Wikimedia sites. It is intended primarily for the use with REST APIs, but is designed to be applicable to other types of APIs as well.

Note that this guideline does not mandate any change to or replacement of the MediaWiki action API. See the bottom opf this page for an exmplanation of how these guidelines relate to Existing APIs.

Existing APIs
This section explains how this guideline relates to pre-existing API.

GitHub

 * No versioning in endpoint URLs, requires  header, see https://docs.github.com/en/rest/overview/api-versions?apiVersion=2022-11-28
 * API spec/doc is versioned by date: https://docs.github.com/de/rest?apiVersion=2022-11-28
 * Breaking changes are announced, generally only addition and removal, e.g. https://developer.github.com/changes/2020-04-15-replacing-create-installation-access-token-endpoint/
 * Uses brownouts!

Amazon

 * Component APIs ("Ads API" vs "SP-API" vs "Product API" vs ...)
 * Deprecation announcement: https://advertising.amazon.com/API/docs/en-us/release-notes/deprecations
 * Introduces (sub)component prefixes into the URL, e.g. /campaigns/ -> sp/campaigns
 * Inconsistent use of version in URL, e.g. /v2/sp/campaigns/ -> sp/campaigns and /sb/beta/campaigns -> /sb/v4/campaigns
 * Spec/doc is versioned by date, e.g. https://developer-docs.amazon.com/sp-api/docs/easyship-api-v2022-03-23-use-case-guide
 * Uses per-region gateways: https://advertising-api.amazon.com vs https://advertising-api-eu.amazon.com

Google

 * A zoo of APIs, e.g.
 * Distance matrix (maps) at https://maps.googleapis.com/maps/api/distancematrix/
 * Route directions (maps) at https://routes.googleapis.com/directions/v2:computeRoutes
 * Search at https://www.googleapis.com/customsearch/v1
 * Knowledge Graph at https://enterpriseknowledgegraph.googleapis.com/v1/
 * Docs at https://docs.googleapis.com/v1/documents.
 * Some of these are RPC APIs, not REST
 * Frequent use of version numbers in the URL
 * Use of component prefixes ("/maps/api/" vs "/directions/")
 * Use of separate entry points ( vs  )

Atlassian (Jira)

 * Version number in the URL, e.g. http://localhost:8080/rest/api/2/issue/createmeta
 * Stability policy https://developer.atlassian.com/platform/marketplace/atlassian-rest-api-policy/ sais: "Wherever possible, REST resources and their representations will be maintained in a backwards compatible manner."
 * This doesn't prevent evolution of the API, because the API version is part of the resource URL.
 * Can use "latest" as version, e.g. http://localhost:8090/jira/rest/api/latest/issue/TST-1/remotelink (really?!)