Pemversian API
| Kebijakan pengusangan |
|---|
| Lihat pula |
This page describes the API versioning policy for RESTBase (aka REST API Wikimedia), which are documented at /api/rest_v1/?doc for each wiki.
Versi API global
Versi API global merupakan bagian dari jalur tersebut.
Contoh:
/v1/
Following the principles of semantic versioning, it is incremented when a stable end point is changed in a backwards-incompatible manner. Untuk versi global, kami menganggap perubahan sebagai perubahan merusak bila titik akhir yang stabil dihapus, atau struktur permintaan berubah dengan cara yang tak kompatibel. Jenis konten diversikan menggunakan runding konten, dan tidak memicu kenaikan versi global. Karena peluncuran versi API utama yang baru merupakan peristiwa yang sangat mengganggu, kami berusaha keras untuk menghindari terganggunya titik akhir yang stabil.
Kestabilan titik akhir
Each API end point is marked with a stability class: Stable, unstable, experimental, deprecated Biasanya, titik akhir API awalnya bersifat eksperimental atau tak stabil, dan seiring waktu berkembang menjadi bagian dari API yang stabil.
Stabil
Titik akhir stabil dijamin tak akan berubah dengan cara yang tak kompatibel. Ini berarti Anda dapat yakin bahwa antarmuka dasar seperti yang didokumentasi oleh spesifikasi akan terus bekerja sebagaimana mestinya.
Tak stabil
End points marked as unstable can change in incompatible ways without incrementing the major API version, but they will increment minor versions. Kami akan menghubungi pengguna dan melakukan upaya bersama untuk menghindari kerugian bagi konsumen yang sudah ada.
Eksperimental
Titik akhir eksperimental dapat berubah dengan cara yang tak kompatibel kapan saja, tanpa menaikkan versi API. Anda dipersilakan untuk menggunakannya dengan risiko Anda sendiri.
Terusangkan
Jika suatu titik akhir ditandai sebagai usang atau terusangkan, itu berarti titik akhir tersebut tak lagi bermanfaat bagi kelayan dan karenanya akan dihapus dalam waktu dekat. Jika kode Anda menggunakan titik akhir semacam itu, Anda harus berhenti menggunakannya sesegera mungkin. Kami akan selalu memastikan untuk menyediakan cara lain bagi pengguna untuk memperoleh informasi yang sama.
Kestabilan dan runding format konten
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.
Latar belakang: Bagaimana kami menafsirkan semver dalam runding format
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 than stored - return stored content
- If the client-requested version is semver major or minor greater than stored version - update the content
- If updated content is matching requested major version and has higher or equal minor version - return
- If updated content has lower major or minor version - return 406 error
- If updated content has higher major version - go to point 3.
- If requested version is semver major lower than stored - transform content to downgrade.
Lihat pula
- 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.