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
 * 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