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
Votre code doit être conçu pour ignorer les champs inconnus dans les réponses afin de rester compatible avec ces évolutions.
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 :
GET https://jobaffinity.fr/restapi/v1
_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
{
"_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)
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)
#!/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 :
Période de transition
Les deux versions (ancienne et nouvelle) restent accessibles simultanément
Tester la nouvelle version
Testez votre intégration avec la nouvelle URL fournie par _last_version_url
Adapter votre code
Effectuez les modifications nécessaires pour la compatibilité
Déployer les changements
Mettez à jour votre code en production avant la date d’expiration
Surveillance post-migration
Vérifiez que tout fonctionne correctement avec la nouvelle version
Changelog
Le changelog est accessible via l’URL fournie dans la réponse racine :
https://jobaffinity.fr/restapi/changelog
- Les nouvelles fonctionnalités
- Les corrections de bugs
- Les changements de comportement
- Les dépréciations
- Les annonces de migration
Consultez régulièrement le changelog pour découvrir les nouvelles possibilités et optimiser votre intégration.
Bonnes pratiques
Conception pour la compatibilité
- Ignorer les champs inconnus : Ne pas échouer sur des champs non reconnus
- Utiliser les URLs fournies : Ne jamais construire d’URLs manuellement
- Versionner votre code : Gardez trace de la version d’API utilisée
- Tester régulièrement : Validez votre intégration à chaque évolution mineure
Exemple de code robuste (Python)
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 :
