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 :

Statut	Description	Comportement
active	Version entièrement prise en charge	Réponses normales avec l’en-tête `X-API-Version`
deprecated	Toujours fonctionnelle mais programmée pour le retrait	Les réponses incluent des en-têtes d’avertissement d’obsolescence
sunset	Retirée du service	Renvoie 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ête	Description
`Deprecation`	Conforme à la RFC 8594 - Date à laquelle la version est devenue obsolète
`Sunset`	Conforme à la RFC 8594 - Date à laquelle la version sera retirée
`X-Deprecated-Message`	Message 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 :

La version précédente est marquée comme obsolète
Vous recevrez des en-têtes d’avertissement pendant une période d’obsolescence recommandée de 6 mois
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

Vérifiez toujours les en-têtes d'obsolescence

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')
  });
}

Spécifiez la version de manière explicite

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: { }

Abonnez-vous aux mises à jour du journal des modifications

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

Testez les nouvelles versions rapidement

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

Guides de Démarrage

Guides avancés

Versionnage de l'API

Guide de versionnage de l’API

Comment spécifier une version

Cycle de vie d’une version

En-têtes de réponse

Pour les versions actives

Pour les versions obsolètes

Réponses d’erreur

En-tête de version non valide

Version non prise en charge

Version retirée (sunset)

Politique de changements incompatibles

Qu’est-ce qui constitue un changement incompatible ?

Bonnes pratiques

Statut de la version actuelle

Ressources connexes

Authentification

Guide de configuration complet

Webhooks

Référence de l'API

​Guide de versionnage de l’API

​Comment spécifier une version

​Cycle de vie d’une version

​En-têtes de réponse

​Pour les versions actives

​Pour les versions obsolètes

​Réponses d’erreur

​En-tête de version non valide

​Version non prise en charge

​Version retirée (sunset)

​Politique de changements incompatibles

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

​Bonnes pratiques

​Statut de la version actuelle

​Ressources connexes

Authentification

Guide de configuration complet

Webhooks

Référence de l'API

Guide de versionnage de l’API

Comment spécifier une version

Cycle de vie d’une version

En-têtes de réponse

Pour les versions actives

Pour les versions obsolètes

Réponses d’erreur

En-tête de version non valide

Version non prise en charge

Version retirée (sunset)

Politique de changements incompatibles

Qu’est-ce qui constitue un changement incompatible ?

Bonnes pratiques

Statut de la version actuelle

Ressources connexes