> ## Documentation Index
> Fetch the complete documentation index at: https://api.jobaffinity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gestion des versions

> Comprendre le versionnement de l'API et les stratégies de migration

## Principe de versionnement

Le numéro de version de l'API est inclus dans l'URL de base :

```
https://jobaffinity.fr/restapi/v1
```

## Modifications sans changement de version

Les modifications suivantes **ne nécessitent pas** de changement de version majeure :

* Modification des URLs (autre que l'URL de base)
* Ajout de nouveaux champs dans une réponse
* Ajout de nouveaux paramètres de requête
* Ajout/suppression/modification des valeurs d'un ENUM
* Modification de la taille des pages de pagination

<Note>
  Votre code doit être conçu pour ignorer les champs inconnus dans les réponses afin de rester compatible avec ces évolutions.
</Note>

## Modifications avec changement de version

Un changement de version majeure (ex: v1 → v2) sera effectué uniquement pour :

* Suppression de champs existants
* Modification du type de données d'un champ
* Changement de comportement incompatible
* Modifications pouvant entraîner un dysfonctionnement des clients

## Surveillance des versions

### Champs à surveiller

Interrogez régulièrement la ressource racine pour surveiller les changements :

```bash theme={null}
GET https://jobaffinity.fr/restapi/v1
```

**Champs importants** :

* **`_version`** : Version mineure actuelle (ex: "1.10")
* **`_last_version_url`** : URL de la dernière version disponible
* **`_expiration`** : Date d'expiration de la version actuelle
* **`_changelog`** : Lien vers l'historique des modifications

### Exemple de réponse

```json theme={null}
{
  "_status": "OK",
  "_self": "/restapi/v1",
  "_version": "1.10",
  "_last_version_url": "/restapi/v1",
  "_expiration": null,
  "_changelog": {
    "_self": "/restapi/changelog"
  }
}
```

### Interprétation

| Situation                      | Signification                              | Action                       |
| ------------------------------ | ------------------------------------------ | ---------------------------- |
| `_last_version_url` == `_self` | Vous utilisez la dernière version          | ✅ Aucune action requise      |
| `_last_version_url` != `_self` | Une nouvelle version est disponible        | ⚠️ Planifier une migration   |
| `_expiration` == `null`        | Pas d'expiration prévue                    | ✅ Version stable             |
| `_expiration` != `null`        | Version sera désactivée à la date indiquée | 🚨 Migration urgente requise |

## Mise en place d'alertes

### Script de surveillance (Python)

```python theme={null}
import requests
from datetime import datetime

def check_api_version():
    """Vérifie l'état de la version de l'API"""
    response = requests.get(
        'https://jobaffinity.fr/restapi/v1',
        auth=('login', 'password')
    )

    data = response.json()

    # Vérifier si une nouvelle version est disponible
    if data['_last_version_url'] != data['_self']:
        print(f"⚠️  ALERTE : Nouvelle version disponible !")
        print(f"   URL actuelle : {data['_self']}")
        print(f"   Nouvelle URL : {data['_last_version_url']}")

    # Vérifier l'expiration
    if data['_expiration']:
        expiration_date = datetime.fromisoformat(data['_expiration'])
        days_remaining = (expiration_date - datetime.now()).days

        print(f"🚨 ALERTE CRITIQUE : Version expire dans {days_remaining} jours")
        print(f"   Date d'expiration : {data['_expiration']}")
        print(f"   Consultez : https://jobaffinity.fr{data['_changelog']['_self']}")

    return data

# Exécuter périodiquement (ex: via cron)
check_api_version()
```

### Script de surveillance (Shell)

```bash theme={null}
#!/bin/bash

RESPONSE=$(curl -s --basic --user "login:password" \
  "https://jobaffinity.fr/restapi/v1")

EXPIRATION=$(echo "$RESPONSE" | jq -r '._expiration // empty')

if [ ! -z "$EXPIRATION" ]; then
  echo "🚨 ALERTE : Version API expire le $EXPIRATION"
  echo "Consultez le changelog pour migrer"
  # Envoyer une alerte (email, Slack, etc.)
  exit 1
fi
```

## Processus de migration

Lorsqu'une nouvelle version majeure est annoncée :

<Steps>
  <Step title="Période de transition">
    Les deux versions (ancienne et nouvelle) restent accessibles simultanément
  </Step>

  <Step title="Tester la nouvelle version">
    Testez votre intégration avec la nouvelle URL fournie par `_last_version_url`
  </Step>

  <Step title="Adapter votre code">
    Effectuez les modifications nécessaires pour la compatibilité
  </Step>

  <Step title="Déployer les changements">
    Mettez à jour votre code en production avant la date d'expiration
  </Step>

  <Step title="Surveillance post-migration">
    Vérifiez que tout fonctionne correctement avec la nouvelle version
  </Step>
</Steps>

## Changelog

Le changelog est accessible via l'URL fournie dans la réponse racine :

```
https://jobaffinity.fr/restapi/changelog
```

Il documente :

* Les nouvelles fonctionnalités
* Les corrections de bugs
* Les changements de comportement
* Les dépréciations
* Les annonces de migration

<Tip>
  Consultez régulièrement le changelog pour découvrir les nouvelles possibilités et optimiser votre intégration.
</Tip>

## Bonnes pratiques

### Conception pour la compatibilité

1. **Ignorer les champs inconnus** : Ne pas échouer sur des champs non reconnus
2. **Utiliser les URLs fournies** : Ne jamais construire d'URLs manuellement
3. **Versionner votre code** : Gardez trace de la version d'API utilisée
4. **Tester régulièrement** : Validez votre intégration à chaque évolution mineure

### Exemple de code robuste (Python)

```python theme={null}
import requests

class JobAffinityAPI:
    def __init__(self, auth):
        self.auth = auth
        self.base_url = 'https://jobaffinity.fr/restapi/v1'

    def get_resource(self, url=None):
        """Récupère une ressource en utilisant les URLs fournies"""
        if url is None:
            url = self.base_url

        response = requests.get(url, auth=self.auth)
        data = response.json()

        # Ignorer les champs inconnus automatiquement
        return data

    def check_version_status(self):
        """Vérifie l'état de la version"""
        root = self.get_resource()

        return {
            'current_version': root.get('_version'),
            'is_latest': root.get('_last_version_url') == root.get('_self'),
            'expiration': root.get('_expiration'),
            'changelog_url': root.get('_changelog', {}).get('_self')
        }

# Utilisation
api = JobAffinityAPI(auth=('login', 'password'))
status = api.check_version_status()

if not status['is_latest']:
    print("⚠️  Nouvelle version disponible")

if status['expiration']:
    print(f"🚨 Migration requise avant {status['expiration']}")
```

## Support

Pour toute question sur la migration :

* Email : [support@intuition-software.fr](mailto:support@intuition-software.fr)
* Le support vous accompagnera durant la période de transition