API versioning - Revision history

Wladek92: ? in a comparison, we use rather 'than' than 'then'

2026-07-30T11:04:57Z

? in a comparison, we use rather 'than' than 'then'

Wladek92: Marked this version for translation

2026-07-30T10:39:52Z

Marked this version for translation

← Older revision		Revision as of 10:39, 30 July 2026
Line 63:		Line 63:
	<translate><!--T:37--> In semantic versioning, all backwards-incompatible changes trigger an increment of the major version number (ex: 1.2.1 to 2.0.0).</translate>		<translate><!--T:37--> In semantic versioning, all backwards-incompatible changes trigger an increment of the major version number (ex: 1.2.1 to 2.0.0).</translate>
	<translate><!--T:38--> As the goal of our format negotiation mechanism is to avoid breaking clients, this is what we are focusing on.</translate>		<translate><!--T:38--> As the goal of our format negotiation mechanism is to avoid breaking clients, this is what we are focusing on.</translate>
	<translate><!--T:39--> Clients are encouraged to provide the exact version they tested with, but the API will typically return the '''''latest''''' content-type that is compatible with the requested '''''major''''' version.</translate> <translate>More specifically, we will return the latest minor version compatible with the requested major version, but won't make guarantees about the returned patch version for performance reasons.</translate>		<translate><!--T:39--> Clients are encouraged to provide the exact version they tested with, but the API will typically return the '''''latest''''' content-type that is compatible with the requested '''''major''''' version.</translate> <translate><!--T:46--> More specifically, we will return the latest minor version compatible with the requested major version, but won't make guarantees about the returned patch version for performance reasons.</translate>

	<translate><!--T:28--> The exact protocol is:</translate>		<translate><!--T:28--> The exact protocol is:</translate>

Wladek92: T:39 dot missing, separate the TU

2026-07-30T10:39:33Z

T:39 dot missing, separate the TU

← Older revision		Revision as of 10:39, 30 July 2026
Line 63:		Line 63:
	<translate><!--T:37--> In semantic versioning, all backwards-incompatible changes trigger an increment of the major version number (ex: 1.2.1 to 2.0.0).</translate>		<translate><!--T:37--> In semantic versioning, all backwards-incompatible changes trigger an increment of the major version number (ex: 1.2.1 to 2.0.0).</translate>
	<translate><!--T:38--> As the goal of our format negotiation mechanism is to avoid breaking clients, this is what we are focusing on.</translate>		<translate><!--T:38--> As the goal of our format negotiation mechanism is to avoid breaking clients, this is what we are focusing on.</translate>
	<translate><!--T:39--> Clients are encouraged to provide the exact version they tested with, but the API will typically return the '''''latest''''' content-type that is compatible with the requested '''''major''''' version More specifically, we will return the latest minor version compatible with the requested major version, but won't make guarantees about the returned patch version for performance reasons.</translate>		<translate><!--T:39--> Clients are encouraged to provide the exact version they tested with, but the API will typically return the '''''latest''''' content-type that is compatible with the requested '''''major''''' version.</translate> <translate>More specifically, we will return the latest minor version compatible with the requested major version, but won't make guarantees about the returned patch version for performance reasons.</translate>

	<translate><!--T:28--> The exact protocol is:</translate>		<translate><!--T:28--> The exact protocol is:</translate>

Wladek92: Marked this version for translation

2026-07-30T09:53:56Z

Marked this version for translation

Wladek92: add translate sections

2026-07-30T09:20:42Z

add translate sections

Wladek92: Marked this version for translation

2026-07-28T18:08:42Z

Marked this version for translation

← Older revision		Revision as of 18:08, 28 July 2026
Line 1:		Line 1:
	<languages/>		<languages/>
	{{Deprecation policies}}		{{Deprecation policies}}
	<translate>This page describes the '''API versioning policy for RESTBase''' (aka <tvar name=1>{{ll\|Wikimedia REST API}}</tvar>), which are documented at [https://en.wikipedia.org/api/rest_v1/?doc /api/rest_v1/?doc] for each wiki.</translate>		<translate><!--T:24--> This page describes the '''API versioning policy for RESTBase''' (aka <tvar name=1>{{ll\|Wikimedia REST API}}</tvar>), which are documented at [https://en.wikipedia.org/api/rest_v1/?doc /api/rest_v1/?doc] for each wiki.</translate>

	<translate>		<translate>
Line 10:		Line 10:
	<code>/v1/</code>		<code>/v1/</code>

	<translate>Following the principles of [<tvar name=url>http://semver.org/</tvar> semantic versioning], it is incremented when a '''stable end point''' is changed in a backwards-incompatible manner.</translate>		<translate><!--T:25--> Following the principles of [<tvar name=url>http://semver.org/</tvar> semantic versioning], it is incremented when a '''stable end point''' is changed in a backwards-incompatible manner.</translate>
	<translate><!--T:12--> For the global version, we consider changes breaking if stable end points are removed, or the request structure changes in incompatible ways.</translate>		<translate><!--T:12--> For the global version, we consider changes breaking if stable end points are removed, or the request structure changes in incompatible ways.</translate>
	<translate><!--T:13--> Content types are versioned using content negotiation, and do not trigger global version increments.</translate>		<translate><!--T:13--> Content types are versioned using content negotiation, and do not trigger global version increments.</translate>
Line 18:		Line 18:
	== End point stability == <!--T:2-->		== End point stability == <!--T:2-->
	</translate>		</translate>
	<translate>Each API end point is marked with a stability class: <tvar name=1>''Stable'', ''unstable'', ''experimental'', ''deprecated''</tvar></translate>		<translate><!--T:26--> Each API end point is marked with a stability class: <tvar name=1>''Stable'', ''unstable'', ''experimental'', ''deprecated''</tvar></translate>
	<translate><!--T:15--> Typically, API end points start out as experimental or unstable, and over time graduate to become part of the stable API.</translate>		<translate><!--T:15--> Typically, API end points start out as experimental or unstable, and over time graduate to become part of the stable API.</translate>

Line 30:		Line 30:
	=== Unstable === <!--T:4-->		=== Unstable === <!--T:4-->
	</translate>		</translate>
	<translate>End points marked as unstable can change in incompatible ways without incrementing the ''major'' API version, but they will increment minor versions.</translate>		<translate><!--T:27--> End points marked as unstable can change in incompatible ways without incrementing the ''major'' API version, but they will increment minor versions.</translate>
	<translate><!--T:18--> We will reach out to users and make a concerted effort to avoid breaking existing consumers.</translate>		<translate><!--T:18--> We will reach out to users and make a concerted effort to avoid breaking existing consumers.</translate>

Line 65:		Line 65:
	Clients are encouraged to provide the exact version they tested with, but the API will typically return the '''''latest''''' content-type that is compatible with the requested '''''major''''' version More specifically, we will return the latest minor version compatible with the requested major version, but won't make guarantees about the returned patch version for performance reasons.		Clients are encouraged to provide the exact version they tested with, but the API will typically return the '''''latest''''' content-type that is compatible with the requested '''''major''''' version More specifically, we will return the latest minor version compatible with the requested major version, but won't make guarantees about the returned patch version for performance reasons.

	<translate>The exact protocol is:</translate>		<translate><!--T:28--> The exact protocol is:</translate>

	# If client-requested version is matching semver ''major'' version and has lower ''minor'' version then stored - return stored content		# If client-requested version is matching semver ''major'' version and has lower ''minor'' version then stored - return stored content
Line 77:		Line 77:
	== See also == <!--T:9-->		== See also == <!--T:9-->
	</translate>		</translate>
	* <translate>The [[<tvar name=1>Specs</tvar>\|Specs page hierarchy on this wiki]] documents versioned content formats.</translate>		* <translate><!--T:29--> The [[<tvar name=1>Specs</tvar>\|Specs page hierarchy on this wiki]] documents versioned content formats.</translate>
	* <translate>See this [[<tvar name=1>Phab:T124365</tvar>\|RFC discussion]] as well as [[<tvar name=2>Talk:API versioning</tvar>\|this section of this article's talk page]] for background on how we arrived at the format versioning strategy outlined here.</translate>		* <translate><!--T:30--> See this [[<tvar name=1>Phab:T124365</tvar>\|RFC discussion]] as well as [[<tvar name=2>Talk:API versioning</tvar>\|this section of this article's talk page]] for background on how we arrived at the format versioning strategy outlined here.</translate>

	[[Category:MediaWiki development{{#translation:}}]]		[[Category:MediaWiki development{{#translation:}}]]

Wladek92: add translate sections

2026-07-28T18:07:59Z

add translate sections

← Older revision		Revision as of 18:07, 28 July 2026
Line 1:		Line 1:
	<languages/>		<languages/>
	{{Deprecation policies}}		{{Deprecation policies}}
	This page describes the '''API versioning policy for RESTBase''' (aka {{ll\|Wikimedia REST API}}), which are documented at [https://en.wikipedia.org/api/rest_v1/?doc /api/rest_v1/?doc] for each wiki.		<translate>This page describes the '''API versioning policy for RESTBase''' (aka <tvar name=1>{{ll\|Wikimedia REST API}}</tvar>), which are documented at [https://en.wikipedia.org/api/rest_v1/?doc /api/rest_v1/?doc] for each wiki.</translate>

	<translate>		<translate>
Line 10:		Line 10:
	<code>/v1/</code>		<code>/v1/</code>

	Following the principles of [http://semver.org/ semantic versioning], it is incremented when a '''stable end point''' is changed in a backwards-incompatible manner.		<translate>Following the principles of [<tvar name=url>http://semver.org/</tvar> semantic versioning], it is incremented when a '''stable end point''' is changed in a backwards-incompatible manner.</translate>
	<translate><!--T:12--> For the global version, we consider changes breaking if stable end points are removed, or the request structure changes in incompatible ways.</translate>		<translate><!--T:12--> For the global version, we consider changes breaking if stable end points are removed, or the request structure changes in incompatible ways.</translate>
	<translate><!--T:13--> Content types are versioned using content negotiation, and do not trigger global version increments.</translate>		<translate><!--T:13--> Content types are versioned using content negotiation, and do not trigger global version increments.</translate>
Line 18:		Line 18:
	== End point stability == <!--T:2-->		== End point stability == <!--T:2-->
	</translate>		</translate>
	Each API end point is marked with a stability class: ''Stable'', ''unstable'', ''experimental'' or ''deprecated''.		<translate>Each API end point is marked with a stability class: <tvar name=1>''Stable'', ''unstable'', ''experimental'', ''deprecated''</tvar></translate>
	<translate><!--T:15--> Typically, API end points start out as experimental or unstable, and over time graduate to become part of the stable API.</translate>		<translate><!--T:15--> Typically, API end points start out as experimental or unstable, and over time graduate to become part of the stable API.</translate>

Line 30:		Line 30:
	=== Unstable === <!--T:4-->		=== Unstable === <!--T:4-->
	</translate>		</translate>
	End points marked as unstable can change in incompatible ways without incrementing the ''major'' API version, but they will increment minor versions.		<translate>End points marked as unstable can change in incompatible ways without incrementing the ''major'' API version, but they will increment minor versions.</translate>
	<translate><!--T:18--> We will reach out to users and make a concerted effort to avoid breaking existing consumers.</translate>		<translate><!--T:18--> We will reach out to users and make a concerted effort to avoid breaking existing consumers.</translate>

Line 65:		Line 65:
	Clients are encouraged to provide the exact version they tested with, but the API will typically return the '''''latest''''' content-type that is compatible with the requested '''''major''''' version More specifically, we will return the latest minor version compatible with the requested major version, but won't make guarantees about the returned patch version for performance reasons.		Clients are encouraged to provide the exact version they tested with, but the API will typically return the '''''latest''''' content-type that is compatible with the requested '''''major''''' version More specifically, we will return the latest minor version compatible with the requested major version, but won't make guarantees about the returned patch version for performance reasons.

	The exact protocol is:		<translate>The exact protocol is:</translate>

	# If client-requested version is matching semver ''major'' version and has lower ''minor'' version then stored - return stored content		# If client-requested version is matching semver ''major'' version and has lower ''minor'' version then stored - return stored content
Line 77:		Line 77:
	== See also == <!--T:9-->		== See also == <!--T:9-->
	</translate>		</translate>
	* The [[Specs\|Specs page hierarchy on this wiki]] documents versioned content formats.		* <translate>The [[<tvar name=1>Specs</tvar>\|Specs page hierarchy on this wiki]] documents versioned content formats.</translate>
	* See this [[Phab:T124365\|RFC discussion]] as well as [[Talk:API versioning\|this section of this article's talk page]] for background on how we arrived at the format versioning strategy outlined here.		* <translate>See this [[<tvar name=1>Phab:T124365</tvar>\|RFC discussion]] as well as [[<tvar name=2>Talk:API versioning</tvar>\|this section of this article's talk page]] for background on how we arrived at the format versioning strategy outlined here.</translate>

	[[Category:MediaWiki development{{#translation:}}]]		[[Category:MediaWiki development{{#translation:}}]]

Shirayuki: Marked this version for translation

2025-12-13T07:42:40Z

Marked this version for translation

← Older revision		Revision as of 07:42, 13 December 2025
Line 6:		Line 6:
	== Global API version == <!--T:1-->		== Global API version == <!--T:1-->
	</translate>		</translate>
	<translate>The global API version is part of the path.</translate>		<translate><!--T:10--> The global API version is part of the path.</translate>
	<translate>Example:</translate>		<translate><!--T:11--> Example:</translate>
	<code>/v1/</code>		<code>/v1/</code>

	Following the principles of [http://semver.org/ semantic versioning], it is incremented when a '''stable end point''' is changed in a backwards-incompatible manner.		Following the principles of [http://semver.org/ semantic versioning], it is incremented when a '''stable end point''' is changed in a backwards-incompatible manner.
	<translate>For the global version, we consider changes breaking if stable end points are removed, or the request structure changes in incompatible ways.</translate>		<translate><!--T:12--> For the global version, we consider changes breaking if stable end points are removed, or the request structure changes in incompatible ways.</translate>
	<translate>Content types are versioned using content negotiation, and do not trigger global version increments.</translate>		<translate><!--T:13--> Content types are versioned using content negotiation, and do not trigger global version increments.</translate>
	<translate>Since the introduction of a new major API version is a very disruptive event, we try hard to avoid breaking stable end points.</translate>		<translate><!--T:14--> Since the introduction of a new major API version is a very disruptive event, we try hard to avoid breaking stable end points.</translate>

	<translate>		<translate>
Line 19:		Line 19:
	</translate>		</translate>
	Each API end point is marked with a stability class: ''Stable'', ''unstable'', ''experimental'' or ''deprecated''.		Each API end point is marked with a stability class: ''Stable'', ''unstable'', ''experimental'' or ''deprecated''.
	<translate>Typically, API end points start out as experimental or unstable, and over time graduate to become part of the stable API.</translate>		<translate><!--T:15--> Typically, API end points start out as experimental or unstable, and over time graduate to become part of the stable API.</translate>

	<translate>		<translate>
	=== Stable === <!--T:3-->		=== Stable === <!--T:3-->
	</translate>		</translate>
	<translate>Stable end points are guaranteed to not change in incompatible ways.</translate>		<translate><!--T:16--> Stable end points are guaranteed to not change in incompatible ways.</translate>
	<translate>This means that you can be sure that the basic interface as documented by the spec will continue to work as described.</translate>		<translate><!--T:17--> This means that you can be sure that the basic interface as documented by the spec will continue to work as described.</translate>

	<translate>		<translate>
Line 31:		Line 31:
	</translate>		</translate>
	End points marked as unstable can change in incompatible ways without incrementing the ''major'' API version, but they will increment minor versions.		End points marked as unstable can change in incompatible ways without incrementing the ''major'' API version, but they will increment minor versions.
	<translate>We will reach out to users and make a concerted effort to avoid breaking existing consumers.</translate>		<translate><!--T:18--> We will reach out to users and make a concerted effort to avoid breaking existing consumers.</translate>

	<translate>		<translate>
	=== Experimental === <!--T:5-->		=== Experimental === <!--T:5-->
	</translate>		</translate>
	<translate>Experimental end points can change in incompatible ways at any time, without incrementing the API version.</translate>		<translate><!--T:19--> Experimental end points can change in incompatible ways at any time, without incrementing the API version.</translate>
	<translate>You are welcome to use them at your own risk.</translate>		<translate><!--T:20--> You are welcome to use them at your own risk.</translate>

	<translate>		<translate>
	=== Deprecated === <!--T:6-->		=== Deprecated === <!--T:6-->
	</translate>		</translate>
	<translate>If an end point is marked as deprecated, it means that it has not been useful to clients and will consequently be removed in the near future.</translate>		<translate><!--T:21--> If an end point is marked as deprecated, it means that it has not been useful to clients and will consequently be removed in the near future.</translate>
	<translate>If your code is using such an end point, you should stop using it as soon as possible.</translate>		<translate><!--T:22--> If your code is using such an end point, you should stop using it as soon as possible.</translate>
	<translate>We will always make sure to provide users with alternative ways of obtaining the same information.</translate>		<translate><!--T:23--> We will always make sure to provide users with alternative ways of obtaining the same information.</translate>

	<translate>		<translate>

Shirayuki: prepare for translation

2025-12-13T07:42:10Z

prepare for translation

← Older revision		Revision as of 07:42, 13 December 2025
Line 1:		Line 1:
	<languages/>		<languages/>
	{{Deprecation policies}}		{{Deprecation policies}}
	This page describes the '''API versioning policy for RESTBase''' (aka [[Wikimedia REST API]]), which are documented at [https://en.wikipedia.org/api/rest_v1/?doc /api/rest_v1/?doc] for each wiki.		This page describes the '''API versioning policy for RESTBase''' (aka {{ll\|Wikimedia REST API}}), which are documented at [https://en.wikipedia.org/api/rest_v1/?doc /api/rest_v1/?doc] for each wiki.

	<translate>		<translate>
	== Global API version == <!--T:1-->		== Global API version == <!--T:1-->
	</translate>		</translate>
	The global API version is part of the path.		<translate>The global API version is part of the path.</translate>
	Example: ~~<code>/v1/~~</~~code~~>.		<translate>Example:</translate>
			<code>/v1/</code>

	Following the principles of [http://semver.org/ semantic versioning], it is incremented when a '''stable end point''' is changed in a backwards-incompatible manner.		Following the principles of [http://semver.org/ semantic versioning], it is incremented when a '''stable end point''' is changed in a backwards-incompatible manner.
	For the global version, we consider changes breaking if stable end points are removed, or the request structure changes in incompatible ways.		<translate>For the global version, we consider changes breaking if stable end points are removed, or the request structure changes in incompatible ways.</translate>
	Content types are versioned using content negotiation, and do not trigger global version increments.		<translate>Content types are versioned using content negotiation, and do not trigger global version increments.</translate>
	Since the introduction of a new major API version is a very disruptive event, we try hard to avoid breaking stable end points.		<translate>Since the introduction of a new major API version is a very disruptive event, we try hard to avoid breaking stable end points.</translate>

	<translate>		<translate>
Line 17:		Line 19:
	</translate>		</translate>
	Each API end point is marked with a stability class: ''Stable'', ''unstable'', ''experimental'' or ''deprecated''.		Each API end point is marked with a stability class: ''Stable'', ''unstable'', ''experimental'' or ''deprecated''.
	Typically, API end points start out as experimental or unstable, and over time graduate to become part of the stable API.		<translate>Typically, API end points start out as experimental or unstable, and over time graduate to become part of the stable API.</translate>

	<translate>		<translate>
	=== Stable === <!--T:3-->		=== Stable === <!--T:3-->
	</translate>		</translate>
	Stable end points are guaranteed to not change in incompatible ways.		<translate>Stable end points are guaranteed to not change in incompatible ways.</translate>
	This means that you can be sure that the basic interface as documented by the spec will continue to work as described.		<translate>This means that you can be sure that the basic interface as documented by the spec will continue to work as described.</translate>

	<translate>		<translate>
Line 29:		Line 31:
	</translate>		</translate>
	End points marked as unstable can change in incompatible ways without incrementing the ''major'' API version, but they will increment minor versions.		End points marked as unstable can change in incompatible ways without incrementing the ''major'' API version, but they will increment minor versions.
	We will reach out to users and make a concerted effort to avoid breaking existing consumers.		<translate>We will reach out to users and make a concerted effort to avoid breaking existing consumers.</translate>

	<translate>		<translate>
	=== Experimental === <!--T:5-->		=== Experimental === <!--T:5-->
	</translate>		</translate>
	Experimental end points can change in incompatible ways at any time, without incrementing the API version.		<translate>Experimental end points can change in incompatible ways at any time, without incrementing the API version.</translate>
	You are welcome to use them at your own risk.		<translate>You are welcome to use them at your own risk.</translate>

	<translate>		<translate>
	=== Deprecated === <!--T:6-->		=== Deprecated === <!--T:6-->
	</translate>		</translate>
	If an end point is marked as deprecated, it means that it has not been useful to clients and will consequently be removed in the near future.		<translate>If an end point is marked as deprecated, it means that it has not been useful to clients and will consequently be removed in the near future.</translate>
	If your code is using such an end point, you should stop using it as soon as possible.		<translate>If your code is using such an end point, you should stop using it as soon as possible.</translate>
	We will always make sure to provide users with alternative ways of obtaining the same information.		<translate>We will always make sure to provide users with alternative ways of obtaining the same information.</translate>

	<translate>		<translate>

Shirayuki: Reverted edits by ~2025-44142-5 (talk) to last version by Clump

2025-08-23T01:29:15Z

Reverted edits by ~2025-44142-5 (talk) to last version by Clump

← Older revision		Revision as of 01:29, 23 August 2025
Line 22:		Line 22:
	=== Stable === <!--T:3-->		=== Stable === <!--T:3-->
	</translate>		</translate>

	Stable end points are guaranteed to not change in incompatible ways.		Stable end points are guaranteed to not change in incompatible ways.
	This means that you can be sure that the basic interface as documented by the spec will continue to work as described. ~~WE KILLINGS EVERYONE BLOCK LOG FRAUD ACCOUNT COMPROMISE~~		This means that you can be sure that the basic interface as documented by the spec will continue to work as described.

	<translate>		<translate>
Line 77:		Line 76:
	</translate>		</translate>
	* The [[Specs\|Specs page hierarchy on this wiki]] documents versioned content formats.		* The [[Specs\|Specs page hierarchy on this wiki]] documents versioned content formats.
	* See this [[Phab:T124365\|RFC discussion]] as well as [[Talk:API versioning\|this section of this article's talk page]] for background on how we arrived at the format versioning strategy outlined ~~block all we all frauds~~		* See this [[Phab:T124365\|RFC discussion]] as well as [[Talk:API versioning\|this section of this article's talk page]] for background on how we arrived at the format versioning strategy outlined here.

	[[Category:MediaWiki development{{#translation:}}]]		[[Category:MediaWiki development{{#translation:}}]]

← Older revision		Revision as of 11:04, 30 July 2026
Line 18:		Line 18:
	== End point stability == <!--T:2-->		== End point stability == <!--T:2-->
	</translate>		</translate>
	<translate><!--T:26--> Each API end point is marked with a stability class: ~~<tvar name=1>~~''Stable'', ''unstable'', ''experimental'', ''deprecated''~~</tvar>~~</translate>		<translate><!--T:26--> Each API end point is marked with a stability class: ''Stable'', ''unstable'', ''experimental'', ''deprecated''</translate>
	<translate><!--T:15--> Typically, API end points start out as experimental or unstable, and over time graduate to become part of the stable API.</translate>		<translate><!--T:15--> Typically, API end points start out as experimental or unstable, and over time graduate to become part of the stable API.</translate>

Line 67:		Line 67:
	<translate><!--T:28--> The exact protocol is:</translate>		<translate><!--T:28--> The exact protocol is:</translate>

	# <translate><!--T:40--> If client-requested version is matching <tvar name=1>semver</tvar> ''major'' version and has lower ''minor'' version ~~then~~ stored - return stored content</translate>		# <translate><!--T:40--> If client-requested version is matching <tvar name=1>semver</tvar> ''major'' version and has lower ''minor'' version than stored - return stored content</translate>
	# <translate><!--T:41--> If the client-requested version is <tvar name=1>semver</tvar> ''major'' or ''minor'' greater ~~then~~ stored version - update the content</translate>		# <translate><!--T:41--> If the client-requested version is <tvar name=1>semver</tvar> ''major'' or ''minor'' greater than stored version - update the content</translate>
	## <translate><!--T:42--> If updated content is matching requested ''major'' version and has higher or equal ''minor'' version - return</translate>		## <translate><!--T:42--> If updated content is matching requested ''major'' version and has higher or equal ''minor'' version - return</translate>
	## <translate><!--T:43--> If updated content has lower ''major'' or ''minor'' version - return 406 error</translate>		## <translate><!--T:43--> If updated content has lower ''major'' or ''minor'' version - return 406 error</translate>
	## <translate><!--T:44--> If updated content has higher major version - go to point 3.</translate>		## <translate><!--T:44--> If updated content has higher major version - go to point 3.</translate>
	# <translate><!--T:45--> If requested version is <tvar name=1>semver</tvar> ''major'' lower ~~then~~ stored - transform content to downgrade.</translate>		# <translate><!--T:45--> If requested version is <tvar name=1>semver</tvar> ''major'' lower than stored - transform content to downgrade.</translate>

	<translate>		<translate>

← Older revision		Revision as of 09:53, 30 July 2026
Line 49:		Line 49:
	== Content format stability and negotiation == <!--T:7-->		== Content format stability and negotiation == <!--T:7-->
	</translate>		</translate>
	<translate>Changes in the structure of the returned content will be clearly indicated by a change in the profile part of the MIME type:</translate>		<translate><!--T:31--> Changes in the structure of the returned content will be clearly indicated by a change in the profile part of the MIME type:</translate>
	text/html; charset=utf-8; profile="[[Specs/HTML/2.0.0\|https://www.mediawiki.org/wiki/Specs/HTML/2.0.0]]"		text/html; charset=utf-8; profile="[[Specs/HTML/2.0.0\|https://www.mediawiki.org/wiki/Specs/HTML/2.0.0]]"
	<translate>For longer-term output format stability, you should send an <tvar name=1><code>Accept</code></tvar> header with the MIME type you expect:</translate>		<translate><!--T:32--> For longer-term output format stability, you should send an <tvar name=1><code>Accept</code></tvar> header with the MIME type you expect:</translate>
	Accept: text/html; charset=utf-8; profile="<nowiki>https://www.mediawiki.org/wiki/Specs/HTML/2.0.0</nowiki>"		Accept: text/html; charset=utf-8; profile="<nowiki>https://www.mediawiki.org/wiki/Specs/HTML/2.0.0</nowiki>"
	<translate>In case of output format changes, the API will then continue to respond with the requested format (subject to semantic versioning protocol, see below), even if a newer format is available.</translate>		<translate><!--T:33--> In case of output format changes, the API will then continue to respond with the requested format (subject to semantic versioning protocol, see below), even if a newer format is available.</translate>
	<translate>Support for old output formats will normally be maintained until usage drops below a low threshold.</translate>		<translate><!--T:34--> Support for old output formats will normally be maintained until usage drops below a low threshold.</translate>
	<translate>Phased-out formats will be announced with ample warning on [[<tvar name=1>mail:mediawiki-api-announce</tvar>\|the API-announce list]].</translate>		<translate><!--T:35--> Phased-out formats will be announced with ample warning on [[<tvar name=1>mail:mediawiki-api-announce</tvar>\|the API-announce list]].</translate>

	<translate>		<translate>
	=== Background: How we interpret <tvar name=1>semver</tvar> in format negotiations === <!--T:8-->		=== Background: How we interpret <tvar name=1>semver</tvar> in format negotiations === <!--T:8-->
	</translate>		</translate>
	<translate>Our profile URLs generally end with a version number based on the [<tvar name=url>http://semver.org/</tvar> <tvar name=1>semver</tvar> semantic versioning scheme].</translate>		<translate><!--T:36--> Our profile URLs generally end with a version number based on the [<tvar name=url>http://semver.org/</tvar> <tvar name=1>semver</tvar> semantic versioning scheme].</translate>
	<translate>In semantic versioning, all backwards-incompatible changes trigger an increment of the major version number (ex: 1.2.1 to 2.0.0).</translate>		<translate><!--T:37--> In semantic versioning, all backwards-incompatible changes trigger an increment of the major version number (ex: 1.2.1 to 2.0.0).</translate>
	<translate>As the goal of our format negotiation mechanism is to avoid breaking clients, this is what we are focusing on.</translate>		<translate><!--T:38--> As the goal of our format negotiation mechanism is to avoid breaking clients, this is what we are focusing on.</translate>
	<translate>Clients are encouraged to provide the exact version they tested with, but the API will typically return the '''''latest''''' content-type that is compatible with the requested '''''major''''' version More specifically, we will return the latest minor version compatible with the requested major version, but won't make guarantees about the returned patch version for performance reasons.</translate>		<translate><!--T:39--> Clients are encouraged to provide the exact version they tested with, but the API will typically return the '''''latest''''' content-type that is compatible with the requested '''''major''''' version More specifically, we will return the latest minor version compatible with the requested major version, but won't make guarantees about the returned patch version for performance reasons.</translate>

	<translate><!--T:28--> The exact protocol is:</translate>		<translate><!--T:28--> The exact protocol is:</translate>

	# <translate>If client-requested version is matching <tvar name=1>semver</tvar> ''major'' version and has lower ''minor'' version then stored - return stored content</translate>		# <translate><!--T:40--> If client-requested version is matching <tvar name=1>semver</tvar> ''major'' version and has lower ''minor'' version then stored - return stored content</translate>
	# <translate>If the client-requested version is <tvar name=1>semver</tvar> ''major'' or ''minor'' greater then stored version - update the content</translate>		# <translate><!--T:41--> If the client-requested version is <tvar name=1>semver</tvar> ''major'' or ''minor'' greater then stored version - update the content</translate>
	## <translate>If updated content is matching requested ''major'' version and has higher or equal ''minor'' version - return</translate>		## <translate><!--T:42--> If updated content is matching requested ''major'' version and has higher or equal ''minor'' version - return</translate>
	## <translate>If updated content has lower ''major'' or ''minor'' version - return 406 error</translate>		## <translate><!--T:43--> If updated content has lower ''major'' or ''minor'' version - return 406 error</translate>
	## <translate>If updated content has higher major version - go to point 3.</translate>		## <translate><!--T:44--> If updated content has higher major version - go to point 3.</translate>
	# <translate>If requested version is <tvar name=1>semver</tvar> ''major'' lower then stored - transform content to downgrade.</translate>		# <translate><!--T:45--> If requested version is <tvar name=1>semver</tvar> ''major'' lower then stored - transform content to downgrade.</translate>

	<translate>		<translate>

← Older revision		Revision as of 09:20, 30 July 2026
Line 49:		Line 49:
	== Content format stability and negotiation == <!--T:7-->		== Content format stability and negotiation == <!--T:7-->
	</translate>		</translate>
	Changes in the structure of the returned content will be clearly indicated by a change in the profile part of the MIME type:		<translate>Changes in the structure of the returned content will be clearly indicated by a change in the profile part of the MIME type:</translate>
	text/html; charset=utf-8; profile="[[Specs/HTML/2.0.0\|https://www.mediawiki.org/wiki/Specs/HTML/2.0.0]]"		text/html; charset=utf-8; profile="[[Specs/HTML/2.0.0\|https://www.mediawiki.org/wiki/Specs/HTML/2.0.0]]"
	For longer-term output format stability, you should send an <code>Accept</code> header with the MIME type you expect:		<translate>For longer-term output format stability, you should send an <tvar name=1><code>Accept</code></tvar> header with the MIME type you expect:</translate>
	Accept: text/html; charset=utf-8; profile="<nowiki>https://www.mediawiki.org/wiki/Specs/HTML/2.0.0</nowiki>"		Accept: text/html; charset=utf-8; profile="<nowiki>https://www.mediawiki.org/wiki/Specs/HTML/2.0.0</nowiki>"
	In case of output format changes, the API will then continue to respond with the requested format (subject to semantic versioning protocol, see below), even if a newer format is available.		<translate>In case of output format changes, the API will then continue to respond with the requested format (subject to semantic versioning protocol, see below), even if a newer format is available.</translate>
	Support for old output formats will normally be maintained until usage drops below a low threshold.		<translate>Support for old output formats will normally be maintained until usage drops below a low threshold.</translate>
	Phased-out formats will be announced with ample warning on [[mail:mediawiki-api-announce\|the API-announce list]].		<translate>Phased-out formats will be announced with ample warning on [[<tvar name=1>mail:mediawiki-api-announce</tvar>\|the API-announce list]].</translate>

	<translate>		<translate>
	=== Background: How we interpret semver in format negotiations === <!--T:8-->		=== Background: How we interpret <tvar name=1>semver</tvar> in format negotiations === <!--T:8-->
	</translate>		</translate>
	Our profile URLs generally end with a version number based on the [http://semver.org/ semver semantic versioning scheme].		<translate>Our profile URLs generally end with a version number based on the [<tvar name=url>http://semver.org/</tvar> <tvar name=1>semver</tvar> semantic versioning scheme].</translate>
	In semantic versioning, all backwards-incompatible changes trigger an increment of the major version number (ex: 1.2.1 to 2.0.0).		<translate>In semantic versioning, all backwards-incompatible changes trigger an increment of the major version number (ex: 1.2.1 to 2.0.0).</translate>
	As the goal of our format negotiation mechanism is to avoid breaking clients, this is what we are focusing on.		<translate>As the goal of our format negotiation mechanism is to avoid breaking clients, this is what we are focusing on.</translate>
	Clients are encouraged to provide the exact version they tested with, but the API will typically return the '''''latest''''' content-type that is compatible with the requested '''''major''''' version More specifically, we will return the latest minor version compatible with the requested major version, but won't make guarantees about the returned patch version for performance reasons.		<translate>Clients are encouraged to provide the exact version they tested with, but the API will typically return the '''''latest''''' content-type that is compatible with the requested '''''major''''' version More specifically, we will return the latest minor version compatible with the requested major version, but won't make guarantees about the returned patch version for performance reasons.</translate>

	<translate><!--T:28--> The exact protocol is:</translate>		<translate><!--T:28--> The exact protocol is:</translate>

	# If client-requested version is matching semver ''major'' version and has lower ''minor'' version then stored - return stored content		# <translate>If client-requested version is matching <tvar name=1>semver</tvar> ''major'' version and has lower ''minor'' version then stored - return stored content</translate>
	# If the client-requested version is semver ''major'' or ''minor'' greater then stored version - update the content		# <translate>If the client-requested version is <tvar name=1>semver</tvar> ''major'' or ''minor'' greater then stored version - update the content</translate>
	## If updated content is matching requested ''major'' version and has higher or equal ''minor'' version - return		## <translate>If updated content is matching requested ''major'' version and has higher or equal ''minor'' version - return</translate>
	## If updated content has lower ''major'' or ''minor'' version - return 406 error		## <translate>If updated content has lower ''major'' or ''minor'' version - return 406 error</translate>
	## If updated content has higher major version - go to point 3.		## <translate>If updated content has higher major version - go to point 3.</translate>
	# If requested version is semver ''major'' lower then stored - transform content to downgrade.		# <translate>If requested version is <tvar name=1>semver</tvar> ''major'' lower then stored - transform content to downgrade.</translate>

	<translate>		<translate>