Technologie et infrastructure → API de versioning

Versioning API

1) Pourquoi est-ce nécessaire

• réduit le risque d'incidents lors des sorties,
• permet l'introduction planifiée d'améliorations et de sécurité,
• donne aux entreprises un calendrier prévisible pour les migrations des partenaires.

2) Classification des changements

PATCH (non cassant) : corrections sans modification de contrat (ajout de champs facultatifs, fiches de validation).
MINOR (extensibles) : extensions back-compatibles (nouveaux endpoints, champs avec default).
MAJOR (cassant) : modification de la structure, sémantique ou suppression des champs/endpoints.

SamVer 'MAJOR est recommandé. MINOR. PATCH'pour les artefacts (SDK/schémas), le numéro « externe » de l'API pouvant être simplifié (v1, v2).

3) Modèles de versioning REST

1. DANS L'URI :

`GET /v1/payments/{id}`

Avantages : Transparent, cachable, facile à acheminer. Inconvénients : duplication de la documentation, plus difficile d'évoluer subtilement.

2. Dans les titres (contenu negotiation) :

`Accept: application/vnd. company. payments. v2+json`

Avantages : flexibilité, pas de « déchets » dans l'URL, évolution pratique de la médiatipe. Inconvénients : il est plus difficile de débiter dans le navigateur, vous avez besoin d'un client discipliné.

3. Dans le titre personnalisé :

`X-API-Version: 2` (или `Api-Version: 2025-09-01`)

Avantages : juste sur le sas. Inconvénients : pas de standard, attention avec le cache.

4. Version-date (date-base) :

Bon pour la fintech/déclaration : « coupes » prévisibles des changements (p. ex. trimestriels).

5. Versionage de la ressource/du modèle :

Recommandation : pour les intégrations externes, les titres « URI vN » + Deprection/Sunset ; pour l'interne - vous pouvez 'Accepter'ou le titre de la version si la passerelle et la plate-forme le prennent en charge.

4) GraphQL

La préférence est sans versions globales. Évolution par ajout de champs/types et privation ('@ deprecated (reason :'...) ').
Les changements cassants ne sont que dans les « grandes » fenêtres (schema namespace versioned) avec le hide migratoire.
Gardez un œil sur « n + 1 » et ne changez pas les champs existants.

5) gRPC / Protobuf

Les numéros de champ sont immuables. Marquer les champs supprimés comme 'reserved'.
Ajoutez des champs en tant qu'option avec default sécurisé.
Utilisez buf breaking/lint pour vérifier automatiquement la compatibilité.
Versez les paquets/modules : 'package payments. v1;` → `payments. v2`.

6) API d'événements (EDA)

Le schéma de l'événement est le même contrat. Conservez-la à Schema Registry (Avro/JSON-Schema/Protobuf).
Topics et versions : 'payments. v1. authorized`, `payments. v2. authorized`.
Les changements cassants sont un nouveau type d'événement ou une nouvelle hache.
Garanties d'évolution : backward-compatible pour les consumers pendant la période LTS.

7) La politique de déchéance et la LEO

• Deprecation : étiquettes dans changelog et dans les spécifications (OpenAPI/GraphQL SDL), en-tête
• 'Deprecation : true 'et quand c'est possible' Sunset : Tu, 31 Mar 2026 00:00:00 UH'.
• Communications : email/portail partenaire, notifications webhooks, release notes.
• Durée : MINOR - 3-6 mois de soutien, MAJOR - 9-18 mois (dépend de la criticité).
• Fenêtres temporelles : fixez dans la « Stratégie de versioning API ».

8) Routage et releases

API Gateway (Kong/Apigee/Nginx/Envoy) : règles par préfixe '/v1/', par titre ou médiatip.

if ($http_accept ~ "vnd.company.payments.v2") { proxy_pass http://payments-v2; }

Canary/Blue-Green/Shadow : roulez une nouvelle version de 1 à 5 % du trafic, comparez les métriques et les logs des erreurs contractuelles.
Feature Flags : Nous cachons le comportement sans changer le contrat.
Migration zero-downtime : sous MAJOR, fournir une double écriture/lecture (dual-write/read) du schéma de données.

9) Contrat-test et contrôle de compatibilité

OpenAPI Diff (ou swagger-diff) : vérifiez que MINOR/PATCH ne brise pas les schémas.
Spectral linting - style, métadonnées obligatoires (version, Deprection).
Contrats de Consommation-Driven (Pact) - assure que le fournisseur ne brise pas les clients.
buf breaking для protobuf.
L'IC doit tomber en cas de changement cassant sans augmentation de MAJOR.

10) Documentation et SDK

Versez les specks : '/docs/api/v1/openapi. json`, `/docs/api/v2/…`.
Générer un SDK par version (npm/maven/pypi) avec BouVer et changelog.
Marquez les méthodes obsolètes dans le SDK avec des annotations/Deprecated.

11) Observability par version

• RPS/latence/erreurs par version ('api _ version' label).
• Cartes d'utilisation des endpoints : qui d'autre sur v1 ?
• Alert : « > 10 % 4xx due to contract mismatch », « anciens clients> X % après la date T ».

12) Mise en cache et versions

La version du chemin améliore la mise en cache du CDN.

• `Vary: Accept, X-API-Version`.
• Ne changez pas la sémantique de réponse dans MINOR pour casser les clés de cache.

13) Sécurité

Ne chiffrez pas la version dans JWT ou ne la transformez pas en JWT - la version définit la requête, pas le jeton.
Ne pas révéler les numéros internes des assemblages. Dans les messages externes, utilisez « v1/v2 ».
Sous MAJOR, revoir la validation, les limites, le masquage des IPI.

14) Migrations et assistants automatiques

Publiez le « Guide de migration v1 → v2 » : tableau de correspondance des champs, exemples de demandes/réponses, cas edge.
Vous proposez des linters pour les clients (CLI) qui mettront en évidence les champs obsolètes.
Pour les grands partenaires - sandbox avec deux versions et datacet de test.

15) Anti-modèles

« Éternel v1 » : absence de deblines et de métriques d'utilisation.
Modifications brisantes cachées dans MINOR/PATCH.
Version dans query string ('? v = 2') : Casse le cache et la lisibilité.
« Un endpoint est une centaine de valeurs de drapeau » : difficile à tester/documenter.

16) Chèque de mise en œuvre

1. Un modèle (URI/Accept/Header) est sélectionné pour les clients externes et internes.
2. BouVer pour les spécifications et SDK, breaking-check automatique dans CI.
3. Politique et modèles de communication de Deprecation/Sunset.
4. Routage Gateway + canaries, dashboards selon les versions.
5. Tests CDC/Contrat sur les intégrations critiques (paiements, KYC, rapports).
6. Documentation/SDK/guide de migration publié en même temps que la version.
7. Plan EOL avec dates et responsables.

17) Exemples

17. 1 REST (URI + titres)

GET /v2/withdrawals/12345
Accept: application/json
Idempotency-Key: 4a1c-…-9f

json
{
"id": "12345",
"status": "PENDING_REVIEW",
"amount": {"value": "100.00", "currency": "EUR"},
"limits": {"daily": "500.00"},
"created_at": "2025-10-02T10:00:00Z",
"links": [{"rel": "cancel", "href": "/v2/withdrawals/12345/cancel", "method": "POST"}]
}

Deprecation: true
Sunset: Tue, 31 Mar 2026 00:00:00 GMT
Link: </v2/docs>; rel="successor-version"

17. 2 Contenu Negotiation (Médiatip)

GET /payments/987
Accept: application/vnd.company.payments.v2+json
Vary: Accept

17. 3 GraphQL (privation de champ)

graphql type Payment {
id: ID!
amount: Money!
status: PaymentStatus!
method: PaymentMethod!
legacyCode: String @deprecated(reason: "Use field `method`")
}

17. 4 gRPC (protobuf)

proto package payments.v2;

message Withdrawal {
string id = 1;
Money amount = 2;
string status = 3; // previously enum, now string with documented values reserved 4; // legacy field removed in v1 -> v2
}

17. 5 Modèle d'événement

• `wallet. v1. balance. updated`
• `wallet. v2. balance. changed '(nouvel événement avec un schéma étendu)

Les schémas sont stockés dans Registry, le producteur ne publie pas les événements avec le schéma qui perturbe la compatibilité.

18) Contexte iGaming/fintech (pratique)

Paiements : entrez v2 pour les nouveaux PSP où 'status '/' decline _ reason' est étendu ; sur le sas mapping v1 → v2 pour le signalement.
KYC : MINOR ajoute le champ 'pep _ screening', les clients v1 ignorent, v2 demande.
Jeux/limites responsables : MAJOR modifie le modèle des limites (journalières/hebdomadaires). Double exportation vers la déclaration avant EOL v1.
Rapports aux régulateurs : versions fixes-dates : 'reporting-2025-01'.

19) Mini-politique (exemple pour le wiki)

Modèle : pour les API externes - 'URI/vN/' ; pour les internes - 'Accept :... vN + json' ou 'X-API-Version : N'.
BouVer : les spécifications et le SDK sont publiés sous le nom de 'N. minor. patch`. MAJOR nécessite RFC/ADR.
Compatibilité : MINOR/PATCH - aucun changement cassant. Une → cassante uniquement via MAJOR.
Deprecation/EOL : annonce en ≥90 jours ; Sunset date dans les titres ; Une branche LTS pour les clients critiques.
Contrôle : OpenAPI bou/buf breaking en IC, CDC pour les intégrations clés.
Observability : métriques/logs avec le label 'api _ version'.
Sorties : canary 5 % ≥ 24h, puis pas à pas jusqu'à 100 % avec des métriques vertes.

Total

Le versioning n'est pas sur « /v2 dans l'URL », mais sur le processus : règles explicites d'évolution, vérifications automatiques de compatibilité, versions gérées et respect des intégrations. Entrez une politique compréhensible, automatisez le contrôle et l'observation - et les changements cesseront d'être une menace pour le produit.