Passer au contenu principal

​
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
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

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

​
Interprétation

SituationSignificationAction
_last_version_url == _selfVous utilisez la dernière version✅ Aucune action requise
_last_version_url != _selfUne nouvelle version est disponible⚠️ Planifier une migration
_expiration == nullPas d’expiration prévue✅ Version stable
_expiration != nullVersion 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 :
1

Période de transition

Les deux versions (ancienne et nouvelle) restent accessibles simultanément
2

Tester la nouvelle version

Testez votre intégration avec la nouvelle URL fournie par _last_version_url
3

Adapter votre code

Effectuez les modifications nécessaires pour la compatibilité
4

Déployer les changements

Mettez à jour votre code en production avant la date d’expiration
5

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
Il documente :
  • 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é

  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)

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 : [email protected]
  • Le support vous accompagnera durant la période de transition