# Versioning

Etant donné que les APIs ReST sont conçues pour être utilisées par de multiples sources *(clients mobiles / web / desktop / partenaires / public…)*, elles évoluent souvent à un **rythme différent de celui des clients**.

Pour s'adapter au changement, il y a trois principales approches :

* Versioning par *Media Type*.
* Versioning par URL.
* Pas de versioning *(la solution à privilégier tant que possible)*.

<https://blog.apisyouwonthate.com/api-versioning-has-no-right-way-f3c75457c0b7>

{% embed url="<https://blog.apisyouwonthate.com/api-versioning-has-no-right-way-f3c75457c0b7>" %}

## Versioning par Media Type

Le versioning par *Media Type* consiste à utiliser le comportement standard des *headers* HTTP `Accept` et `Content-Type`.

Le client indique alors la version de l’API qu’il supporte dans le header `Accept` :\
`Accept: application/vnd.wishtack.v3+json`

L’API retourne alors les données dans la version correspondante avec le bon *Media Type* dans le header `Content-Type`.

* Séduisant mais légèrement complexe à mettre en place.
* Comment faire si la nouvelle version est implémentée dans un langage différent ou encore sur une plateforme différente ?
* Nous serions alors obligé d’utiliser un connecteur pour effectuer le *balancing*.\
  <https://github.com/Kong/kong/issues/402>

## Versioning par URL

Vu l’obstacle de *balancing* posé par le versioning par *Media Type,* pourquoi ne pas utiliser un *balancing* standard en amont… mais lequel ?

Nous pourrions utiliser le *path* de l’URL et procéder au ***balancing*****&#x20;en fonction du nom de domaine**. Cela nécessite toujours un connecteur : <https://getkong.org/docs/0.13.x/proxy/#request-path> mais c'est une approche un peu plus classique et plus facile à configurer.

{% tabs %}
{% tab title="🧐" %}
Qui dit mieux ?
{% endtab %}

{% tab title="👍" %}
Yes ! Le DNS !\
\
[`https://v1.api.wishtack.com`](https://v1.api.wishtack.com/) NodeJS hosted on Amazon.\
[`https://v2.api.wishtack.com`](https://v2.api.wishtack.com/) Python hosted on Heroku.\
[`https://v3.api.wishtack.com`](https://v3.api.wishtack.com/) Python hosted on Heroku sur un monorépo avec l’API V2.[`https://v4.api.wishtack.com`](https://v3.api.wishtack.com/) Serverless functions sur un monorépo avec l’API V2 et V3.
{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://guide-api-rest.marmicode.fr/conventions-et-bonnes-pratiques/versioning.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.