Change Details

"As a Client Developer, I want to know the [[ https://semver.org/ | semantic version ]] of the API, so that I can depend on the endpoints I use." One of the most difficult parts of developing an API client for a live site is changes in the interface. We should make sure as we develop the REST API that it's clear what endpoints and functionality is a supported, production endpoint subject to our version policy. Ideally, we will have minor releases that more or less map to the epics in phabricator. So: - version 1.0: Page History T231338 - version 1.1: Page History + Minimal Client T229662 - version 1.2: Page History + Minimal Client + Media T234944 - version 1.3: Page History + Minimal Client + Media + Extended History T234951 To keep our development in accord with the versioning and namespace RFC T232485, especially w/r/t unstable interfaces, we should: 1. Add new endpoints to a development namespace, `/coredev/v0`. `coredev` here means "core development", and `v0` means a semantic version 0, or "no promises, can change at any time". 2. When we add new features to an existing endpoint (by adding properties to the output, or by accepting different parameters or input), we should have two versions: the version with new features in `/coredev/v0`, and the version without them in `/v1`. 3. When we finish an epic and are ready to release, we remove all the endpoints in the development namespace, and add them to the production `/v1` namespace, and we increment the minor version of the API (1.0 -> 1.1, 1.1 -> 1.2, ...).

"As a Client Developer, I want to know the [[ https://semver.org/ | semantic version ]] of the API, so that I can depend on the endpoints I use." One of the most difficult parts of developing an API client for a live site is changes in the interface. We should make sure as we develop the REST API that it's clear what endpoints and functionality is a supported, production endpoint subject to our version policy. Ideally, we will have minor releases that more or less map to the epics in phabricator. So: - version 1.0: Page History T231338 - version 1.1: Page History + Minimal Client T229662 - version 1.2: Page History + Minimal Client + Media T234944 - version 1.3: Page History + Minimal Client + Media + Extended History T234951 To keep our development in accord with the versioning and namespace RFC T232485, especially w/r/t unstable interfaces, we should: 1. Add new endpoints to a development namespace, `/coredev/v0`. `coredev` here means "core development", and `v0` means a semantic version 0, or "no promises, can change at any time". 2. When we add new features to an existing endpoint (by adding properties to the output, or by accepting different parameters or input), we should have two versions: the version with new features in `/coredev/v0`, and the version without them in `/v1`. 3. When we finish an epic and are ready to release, we remove all the endpoints in the development namespace, and add them to the production `/v1` namespace, and we increment the minor version of the API (1.0 -> 1.1, 1.1 -> 1.2, ...). 4. We should have an API version information endpoint; see below. ---- GET /version Returns version information for the MediaWiki REST API. Request body: none Notable request headers: none Status codes: - 200: the body includes the version information for the MediaWiki REST API. Notable response headers: none Response body: JSON, an object with the following properties * api: major and minor numbers of the semantic version of the API, as a string; ex. "1.1" * mediawiki: version of mediawiki running on this server

"As a Client Developer, I want to know the [[ https://semver.org/ | semantic version ]] of the API, so that I can depend on the endpoints I use." One of the most difficult parts of developing an API client for a live site is changes in the interface. We should make sure as we develop the REST API that it's clear what endpoints and functionality is a supported, production endpoint subject to our version policy. Ideally, we will have minor releases that more or less map to the epics in phabricator. So: - version 1.0: Page History T231338 - version 1.1: Page History + Minimal Client T229662 - version 1.2: Page History + Minimal Client + Media T234944 - version 1.3: Page History + Minimal Client + Media + Extended History T234951 To keep our development in accord with the versioning and namespace RFC T232485, especially w/r/t unstable interfaces, we should: 1. Add new endpoints to a development namespace, `/coredev/v0`. `coredev` here means "core development", and `v0` means a semantic version 0, or "no promises, can change at any time". 2. When we add new features to an existing endpoint (by adding properties to the output, or by accepting different parameters or input), we should have two versions: the version with new features in `/coredev/v0`, and the version without them in `/v1`. 3. When we finish an epic and are ready to release, we remove all the endpoints in the development namespace, and add them to the production `/v1` namespace, and we increment the minor version of the API (1.0 -> 1.1, 1.1 -> 1.2, ...). 4. We should have an API version information endpoint; see below. ---- GET /version Returns version information for the MediaWiki REST API. Request body: none Notable request headers: none Status codes: - 200: the body includes the version information for the MediaWiki REST API. Notable response headers: none Response body: JSON, an object with the following properties * api: major and minor numbers of the semantic version of the API, as a string; ex. "1.1" * mediawiki: version of mediawiki running on this server