API versiebeheer

This page is a translated version of the page API versioning and the translation is 100% complete.

This page describes the API versioning policy for RESTBase (aka Wikimedia REST API ), which are documented at /api/rest_v1/?doc for each wiki.

Globale API-versie

De globale API-versie is onderdeel van het pad. Voorbeeld: /v1/

Following the principles of semantic versioning, it is incremented when a stable end point is changed in a backwards-incompatible manner. Voor de globale versie beschouwen we veranderingen als groot als we de stabiele eindpunten verwijderen of de verzoekstructuur op een onverenigbare manier veranderen. Inhoudstypen worden verwerkt met behulp van inhoud-onderhandelingen en veroorzaken geen globale versie-verandering. Aangezien de introductie van een nieuwe grote API-versie een zeer verstorend evenement is, proberen we hard om voor de gebruikers relevante wijzigingen van stabiele eindpunten te vermijden.

Eindpunt stabiliteit

Each API end point is marked with a stability class: Stable, unstable, experimental or deprecated. API-eindpunten beginnen als experimentele of onstabiel, en met de tijd worden ze deel van de stabiele API.

Stabiel

Van stabiele eindpunten wordt gegarandeerd dat ze niet onverenigbaar veranderen. Dit betekent dat u er zeker van kunt zijn dat de basisinterface zoals gedocumenteerd in de specificatie zal blijven werken zoals is beschreven.

Onstabiel

End points marked as unstable can change in incompatible ways without incrementing the major API version, but they will increment minor versions. Wij zullen de gebruikers benaderen en een inspanning doen om wijzigingen voor bestaande gebruikers te vermijden.

Experimenteel

Experimentele eindpunten kunnen op elk moment onverenigbaar veranderen, zonder de API-versie te wijzigen. Het door u gebruiken van experimentele eindpunten is voor uw eigen risico.

Verouderd

Als een eindpunt als verouderd/ontraden wordt gemarkeerd, betekent dit dat het niet nuttig is geweest voor de gebruikers en daarom binnenkort kan worden verwijderd. Als uw code zo'n eindpunt gebruikt, moet u de code zo snel mogelijk aanpassen. We zullen er altijd voor zorgen dat gebruikers alternatieve manieren krijgen om dezelfde informatie te verkrijgen.

Inhoud formaat stabiliteit en onderhandeling

Changes in the structure of the returned content will be clearly indicated by a change in the profile part of the MIME type:

text/html; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/HTML/2.0.0"

For longer-term output format stability, you should send an Accept header with the MIME type you expect:

Accept: text/html; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/HTML/2.0.0"

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. Support for old output formats will normally be maintained until usage drops below a low threshold. Phased-out formats will be announced with ample warning on the API-announce list.

Achtergrond: Hoe zien we 'semver' in formaat onderhandelingen

Our profile URLs generally end with a version number based on the semver semantic versioning scheme. In semantic versioning, all backwards-incompatible changes trigger an increment of the major version number (ex: 1.2.1 to 2.0.0). As the goal of our format negotiation mechanism is to avoid breaking clients, this is what we are focusing on. 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:

If client-requested version is matching semver major version and has lower minor version then stored - return stored content
If the client-requested version is semver major or minor greater then stored version - update the content
1. If updated content is matching requested major version and has higher or equal minor version - return
2. If updated content has lower major or minor version - return 406 error
3. If updated content has higher major version - go to point 3.
If requested version is semver major lower then stored - transform content to downgrade.

Zie ook

The Specs page hierarchy on this wiki documents versioned content formats.
See this RFC discussion as well as this section of this article's talk page for background on how we arrived at the format versioning strategy outlined here.