Τεχνολογία και υποδομή - Έκδοση API

Έκδοση API

1) Γιατί το χρειάζεστε

• μειώνει τον κίνδυνο συμβάντων κατά τη διάρκεια των απελευθερώσεων,
• σας επιτρέπει να προγραμματίσετε βελτιώσεις και ασφάλεια,
• παρέχει στις επιχειρήσεις προβλέψιμα χρονοδιαγράμματα για τη μετανάστευση εταίρων.

2) Ταξινόμηση των αλλαγών

PATCH (όχι διακοπή): διορθώσεις χωρίς αλλαγή της σύμβασης (προσθήκη προαιρετικών πεδίων, διορθώσεων επικύρωσης).
MINOR: αναδρομικά συμβατές επεκτάσεις (νέα τελικά σημεία, πεδία με προεπιλογή).
MAJOR (θραύση): αλλαγή της δομής, σημασιολογία ή διαγραφή πεδίων/τελικών σημείων.

Συνιστάται το SemVer 'MAJOR. MINOR. PATCH 'για τεχνουργήματα (SDK/σχήματα), ενώ ο «εξωτερικός» αριθμός API μπορεί να απλοποιηθεί (v1, v2).

3) Μοντέλα έκδοσης ανάπαυσης

1. ΣΤΟ URI:

«GET/v1/πληρωμές/{ id}»

Επαγγελματίες: διαφανείς, εφικτές, εύκολες στη διαδρομή. Κατά: επικάλυψη της τεκμηρίωσης, πιο δύσκολο να εξελιχθεί διακριτικά.

2. Στις κεφαλίδες (διαπραγμάτευση περιεχομένου):

'Αποδοχή: εφαρμογή/vnd. εταιρεία. πληρωμές. v2 + json "

Υπέρ: ευελιξία, όχι «σκουπίδια» στο URL, βολική εξέλιξη του τύπου των μέσων ενημέρωσης. Κατά: είναι πιο δύσκολο να αποσφαλματωθεί στο πρόγραμμα περιήγησης, χρειάζεστε έναν πειθαρχημένο πελάτη.

3. Σε προσαρμοσμένη κεφαλίδα:

«X-API-Version: 2» (или 'Api-Version: 2025-09-01')

Pros: μόνο στο sluice. Κατά: καμία τυποποίηση, προσεκτική με την κρύπτη.

4. Έκδοση με βάση την ημερομηνία:

Καλό για fintech/υποβολή εκθέσεων: προβλέψιμες «περικοπές» μεταβολών (π.χ. τριμηνιαία).

5. Έκδοση πόρου/μοντέλου:

Σύσταση: για εξωτερικές ενοποιήσεις - Κεφαλίδες «URI vN» + Απόρριψη/Ηλιοβασίλεμα. για εσωτερικό - μπορείτε να «αποδεχθείτε» ή την επικεφαλίδα έκδοσης, εάν η πύλη και η πλατφόρμα την υποστηρίζουν.

4) GraphQL

Προτίμηση - καμία παγκόσμια έκδοση. Εξέλιξη μέσω προσθήκης πεδίων/τύπων και αποδυνάμωσης ('@ deprecredated (λόγος:... "")').
Σπάζοντας αλλαγές - μόνο σε «μεγάλα» παράθυρα (versioned schema namespace) με οδηγό μετανάστευσης.
Παρακολουθήστε για το «n + 1» και μην αλλάξετε την έννοια των υπαρχόντων πεδίων.

5) gRPC/Protobuf

Οι αριθμοί πεδίου είναι αμετάβλητοι. Σημειώστε τα διαγραμμένα πεδία ως «δεσμευμένα».
Προσθήκη πεδίων ως προαιρετικά με ασφαλή προεπιλογή.
Χρήση buf breaking/lint για αυτόματο έλεγχο συμβατότητας.
Πακέτα/ενότητες έκδοσης: "πληρωμές πακέτων. v1· πληρωμές «→». v2 '.

6) API γεγονότων (ΕΟΑ)

Το σύστημα εκδήλωσης είναι η ίδια σύμβαση. Αποθηκεύεται στο μητρώο Schema (Avro/JSON-Schema/Protobuf).
Θέματα και εκδόσεις: "πληρωμές. v1. επιτρεπόμενες πληρωμές «,». v2. εγκεκριμένο ".
Σπάζοντας αλλαγές - ένα νέο είδος γεγονότος ή ένα νέο θέμα.
Εγγυήσεις εξέλιξης: προς τα πίσω συμβατές για τους καταναλωτές κατά την περίοδο LTS.

7) Πολιτική εξυγίανσης και EOL

• Αποπροσανατολισμός: ετικέτες σε changelog και σε προδιαγραφές (OpenAPI/GraphQL SDL), κεφαλίδα
• 'Κατάθλιψη: αλήθεια' και όταν είναι δυνατόν 'Ηλιοβασίλεμα: Tue, 31 Mar 2026 00:00 GMT'.
• Επικοινωνίες: πύλη ηλεκτρονικού ταχυδρομείου/συνεργάτη, ειδοποιήσεις webhooks, σημειώσεις έκδοσης.
• Όροι: MINOR - 3-6 μήνες στήριξης, MAJOR - 9-18 μήνες (ανάλογα με την κρισιμότητα).
• Χρονικά παράθυρα: καθορίστε το «API Versioning Policy».

8) Δρομολόγηση και απελευθερώσεις

Πύλη API (Kong/Apigee/Nginx/Envoy): κανόνες με πρόθεμα '/v1/', με κεφαλίδα ή μεσάζοντα.

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

Canary/Blue-Green/Shadow: κυλήστε τη νέα έκδοση στο 1-5% της κυκλοφορίας, συγκρίνετε μετρήσεις και καταγραφές των συμβατικών σφαλμάτων.
Σημαίες χαρακτηριστικών: Απόκρυψη συμπεριφοράς χωρίς αλλαγή συμβολαίου.
Μετάβαση μηδενικού χρόνου: με MAJOR, παρέχεται διπλή εγγραφή/ανάγνωση του σχήματος δεδομένων.

9) Έλεγχος συμβάσεων και έλεγχος συμβατότητας

OpenAPI Diff (ή swagger-diff) - Ελέγξτε ότι το MINOR/PATCH δεν σπάει σχήματα.
Φασματική επένδυση - στυλ, απαιτούμενα μεταδεδομένα (έκδοση, αποσύνθεση).
Συμβάσεις με γνώμονα τους καταναλωτές (σύμφωνο) - εξασφαλίζει ότι ο πάροχος δεν διακόπτει τους πελάτες.
σπάσιμο buf для protobuf.
Η ΚΚΠ θα πρέπει να πέσει σε ρήξη των αλλαγών χωρίς αύξηση του MAJOR.

10) Τεκμηρίωση και SDK

Έκδοση των προδιαγραφών: '/docs/api/v1/openapi. json ', '/docs/api/v2/...'.
Δημιουργήστε SDK με έκδοση (npm/maven/pypi) με SemVer και changelog.
Ο Μαρκ απέρριψε τις μεθόδους στο SDK με/υποτιμημένες σημειώσεις.

11) Παρατήρηση ανά έκδοση

• RPS/καθυστέρηση/σφάλματα ανά έκδοση (ετικέτα 'api _ version').
• Χάρτες χρήσης τελικού σημείου: Ποιος άλλος είναι στο v1
• Καταχωρίσεις: «> 10% 4xx λόγω αναντιστοιχίας συμβάσεων», «παλαιοί πελάτες> X% μετά την ημερομηνία T».

12) Αποθήκευση και εκδόσεις

Η έκδοση κατά τη διαμετακόμιση βελτιώνει την cachability CDN.

• 'Vary: Αποδοχή, X-API-Version'.
• Μην αλλάξετε τη σημασιολογία της απόκρισης στο MINOR για να σπάσει τα κλειδιά της κρύπτης.

13) Ασφάλεια

Μην κρυπτογραφήσετε ή ράψετε την έκδοση στο JWT - η έκδοση καθορίζεται από το αίτημα, όχι από το σύμβολο.
Μην αποκαλύπτετε εσωτερικούς αριθμούς συναρμολόγησης. Χρήση του «v1/v2» για εξωτερικά μηνύματα.
Στο MAJOR, επανεξέταση επικύρωσης, όρια, συγκάλυψη PII.

14) Μετανάστευση και αυτοβοήθειες

Δημοσίευση «Οδηγός μετανάστευσης v1 → v2»: πίνακας χαρτογράφησης πεδίου, αιτήσεις δειγματοληψίας/απαντήσεις, περιπτώσεις άκρων.
Προσφέρουμε προσαρτήματα για πελάτες (CLI) που αναδεικνύουν ξεπερασμένα πεδία.
Για μεγάλους συντρόφους - sandbox με δύο εκδόσεις και ένα σύνολο δεδομένων δοκιμών.

15) Αντι-μοτίβα

«Eternal v1»: έλλειψη προθεσμιών και μετρήσεων χρήσης.
Κρυφές αλλαγές θραύσης στο MINOR/PATCH.
«Έκδοση στη συμβολοσειρά ερωτήσεων» ('? v = 2 ') - σπάει η μνήμη και η αναγνωσιμότητα.
«Ένα τελικό σημείο είναι εκατό τιμές σημαίας»: δύσκολο να ελεγχθεί/τεκμηριωθεί.

16) Κατάλογος ελέγχου εφαρμογής

1. Επιλεγμένο μοντέλο (URI/Αποδοχή/Κεφαλίδα) για εξωτερικούς και εσωτερικούς πελάτες.
2. SemVer για προδιαγραφές και SDK, αυτόματος έλεγχος θραύσης σε CI.
3. Απερήμωση/Sunset policy και υποδείγματα επικοινωνίας.
4. Δρομολόγηση πύλης + καναρίνια, ταμπλό κατά έκδοση.
5. Δοκιμές CDC/Συμβάσεις για κρίσιμες ενότητες (πληρωμές, KYC, υποβολή εκθέσεων).
6. Ο οδηγός τεκμηρίωσης/SDK/μετανάστευσης δημοσιεύεται ταυτόχρονα με την έκδοση.
7. Σχέδιο EOL με ημερομηνίες και ευθύνη.

17) Παραδείγματα

17. 1 REST (κεφαλίδες URI +)

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 Διαπραγμάτευση περιεχομένου

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

17. 3 GraphQL (Μείωση πεδίου)

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 Μοντέλο γεγονότων

• "wallet. v1. ισορροπία. επικαιροποίηση "
• "wallet. v2. ισορροπία. αλλαγή '(νέο γεγονός με εκτεταμένο σχήμα)

Τα συστήματα αποθηκεύονται στο μητρώο, ο παραγωγός δεν δημοσιεύει γεγονότα με σύστημα που παραβιάζει τη συμβατότητα.

18) Πλαίσιο iGaming/fintech (πρακτική)

Πληρωμές: εισροή v2 για νέους παρόχους υπηρεσιών πληρωμών όπου επεκτείνεται το «status »/« decide _ reason»· στην πύλη, χαρτογράφηση v1 → v2 για την υποβολή εκθέσεων.
KYC: MINOR προσθέτει πεδίο 'pep _ screening', οι πελάτες αγνοούν v1, v2 - απαιτεί.
Υπεύθυνα παιχνίδια/όρια: MAJOR αλλάζει το μοντέλο ορίων (ημερήσια/εβδομαδιαία). Διπλή εξαγωγή σε αναφορά πριν από την EOL v1.
Υποβολή εκθέσεων στις ρυθμιστικές αρχές: καθορισμένες εκδόσεις-ημερομηνίες: «υποβολή εκθέσεων-2025-01».

19) Μίνι πολιτική (π.χ. wiki)

Υπόδειγμα: για εξωτερικά API - «URI/vN/». για εσωτερικό - "Αποδοχή:... vN + json 'ή' X-API-Version: N '.
SemVer: Οι προδιαγραφές και τα SDK δημοσιεύονται ως 'N. ελάσσονος σημασίας. έµπλαστρο '. MAJOR απαιτεί RFC/ADR.
Συμβατότητα: MINOR/PATCH - καμία αλλαγή θραύσης. Σπάζοντας → μόνο μέσω του MAJOR.
Απερήμωση/EOL: Ανακοίνωση ημέρας ≥90; Ημερομηνία λήξης στα πρωτοσέλιδα. υποκατάστημα LTS για κρίσιμους πελάτες.
Έλεγχος: Σπάσιμο OpenAPI diff/buf σε CI, CDC για ενοποιήσεις κλειδιών.
Παρατηρησιμότητα: μετρήσεις/καταγραφές με ετικέτα «api _ version».
Κυκλοφορίες: καναρίνι 5% ≥ 24 ώρες, στη συνέχεια σε στάδια έως 100% με πράσινες μετρήσεις.

Αποτέλεσμα

Η έκδοση δεν αφορά το «/v2 στο URL «, αλλά τη διαδικασία: σαφείς κανόνες εξέλιξης, αυτόματους ελέγχους συμβατότητας, ελεγχόμενες εκλύσεις και σεβασμό για την ολοκλήρωση. Εισάγετε μια σαφή πολιτική, αυτοματοποιήστε την παρακολούθηση και την παρατηρησιμότητα - και οι αλλαγές δεν θα αποτελούν πλέον απειλή για το προϊόν.