Passer au contenu principal

​
Guide de versionnage de l’API

L’API Firma utilise un versionnage basé sur les en-têtes via l’en-tête X-API-Version. Cela vous permet de spécifier quelle version de l’API vous souhaitez utiliser, avec des avertissements d’obsolescence automatiques et un processus de retrait structuré.

​
Comment spécifier une version

Incluez l’en-tête X-API-Version dans votre requête : 
curl https://api.firma.dev/functions/v1/signing-request-api/signing-requests \
  -H "X-API-Version: 1" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
  {
    headers: {
      'X-API-Version': '1',
      'Authorization': `Bearer ${process.env.FIRMA_API_KEY}`
    }
  }
);

import requests

headers = {
    'X-API-Version': '1',
    'Authorization': f'Bearer {os.environ["FIRMA_API_KEY"]}'
}

response = requests.get(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests',
    headers=headers
)
Si l’en-tête X-API-Version est omis, l’API utilise par défaut la version stable actuelle (actuellement 1).

​
Cycle de vie d’une version

Chaque version de l’API passe par trois étapes :
StatutDescriptionComportement
activeVersion entièrement prise en chargeRéponses normales avec l’en-tête X-API-Version
deprecatedToujours fonctionnelle mais programmée pour le retraitLes réponses incluent des en-têtes d’avertissement d’obsolescence
sunsetRetirée du serviceRenvoie l’erreur 410 Gone

​
En-têtes de réponse

​
Pour les versions actives

X-API-Version: 1

​
Pour les versions obsolètes

Lorsqu’une version devient obsolète, les en-têtes suivants sont inclus dans chaque réponse : 
X-API-Version: 1
Deprecation: 2025-06-01
Sunset: 2025-12-01
X-Deprecated-Message: This API version is deprecated and will be removed on 2025-12-01. Please migrate to version 2.
En-têteDescription
DeprecationConforme à la RFC 8594 - Date à laquelle la version est devenue obsolète
SunsetConforme à la RFC 8594 - Date à laquelle la version sera retirée
X-Deprecated-MessageMessage d’avertissement lisible par un humain

​
Réponses d’erreur

​
En-tête de version non valide

// 400 Bad Request
{
  "error": "Invalid X-API-Version header. Must be a positive integer.",
  "code": "INVALID_VERSION"
}

​
Version non prise en charge

// 400 Bad Request
{
  "error": "API version 99 is not supported. Supported versions: 1",
  "code": "UNSUPPORTED_VERSION"
}

​
Version retirée (sunset)

// 410 Gone
{
  "error": "API version 1 has been removed as of 2025-12-01. Please migrate to version 2.",
  "code": "VERSION_SUNSET"
}

​
Politique de changements incompatibles

Les changements incompatibles ne sont introduits que lors des incréments de version majeure (par exemple, v1 → v2). Les changements compatibles, tels que de nouveaux champs optionnels ou de nouveaux endpoints, ne nécessitent pas de nouvelle version.
Lorsqu’une nouvelle version majeure est publiée :
  1. La version précédente est marquée comme obsolète
  2. Vous recevrez des en-têtes d’avertissement pendant une période d’obsolescence recommandée de 6 mois
  3. Après la date de retrait, l’ancienne version renvoie 410 Gone

​
Qu’est-ce qui constitue un changement incompatible ?

Les changements incompatibles incluent :
  • Supprimer ou renommer des champs existants
  • Modifier les types de champs ou les règles de validation
  • Supprimer des endpoints
  • Modifier les exigences d’authentification
  • Modifier les limites de débit de manière significative
Les changements compatibles incluent :
  • Ajouter de nouveaux champs optionnels
  • Ajouter de nouveaux endpoints
  • Ajouter de nouvelles valeurs d’énumération (si votre client gère correctement les valeurs inconnues)
  • Améliorer les messages d’erreur

​
Bonnes pratiques

Implémentez des vérifications automatisées dans le code de votre client API pour détecter les en-têtes Deprecation et Sunset. Enregistrez des avertissements lorsque ces en-têtes sont présents.
const response = await fetch(url, options);

if (response.headers.get('Deprecation')) {
  console.warn('API Deprecation Warning:', {
    deprecation: response.headers.get('Deprecation'),
    sunset: response.headers.get('Sunset'),
    message: response.headers.get('X-Deprecated-Message')
  });
}
Plutôt que de vous fier à la version par défaut, spécifiez toujours l’en-tête X-API-Version de manière explicite. Cela évite les changements incompatibles inattendus lorsque la version par défaut change.
// Bien - version explicite
headers: { 'X-API-Version': '1' }

// À éviter - dépend de la valeur par défaut
headers: { }
Restez informé des changements à venir en vous abonnant au journal des modifications ou aux annonces de l’API. Cela vous donne un préavis concernant :
  • Les nouvelles publications de versions
  • Les calendriers d’obsolescence
  • Les changements incompatibles
  • Les guides de migration
Lorsqu’une nouvelle version est annoncée, testez votre intégration avec elle bien avant la date de retrait de l’ancienne version. Cela vous donne le temps de :
  • Identifier les changements incompatibles dans votre implémentation
  • Mettre à jour votre code et vos dépendances
  • Tester minutieusement dans un environnement de préproduction
  • Déployer en toute confiance avant la date limite

​
Statut de la version actuelle

La version active actuelle est v1, sans aucune obsolescence programmée pour le moment.
Lorsque de nouvelles versions seront publiées ou que des calendriers d’obsolescence seront annoncés, ce guide sera mis à jour avec les dates spécifiques et les informations de migration.

​
Ressources connexes

Authentification

Découvrez l’authentification par Clé API et les jetons JWT

Guide de configuration complet

Démarrez avec l’API Firma

Webhooks

Configurez les notifications webhook pour les événements

Référence de l'API

Parcourez tous les endpoints de l’API