Πράξεις API

(Τμήμα: Πράξεις και διαχείριση)

1) Σκοπός και αρχές

Το API είναι το «λειτουργικό επίπεδο» του οικοσυστήματος: οτιδήποτε δεν αυτοματοποιείται μέσω σύμβασης μετατρέπεται σε χειρωνακτική εργασία και κίνδυνο.

• Πρώτη σύμβαση: πρώτη προδιαγραφή (OpenAPI/JSON Schema/AsyncAPI), στη συνέχεια εφαρμογή.
• Ασφαλής εξ ορισμού: ελάχιστα πεδία εφαρμογής, σύντομη TTL, αμοιβαία TLS/υπογραφές.
• Παρατηρήσιμη: ανίχνευση από άκρο σε άκρο και μετρήσεις SLA.
• Idempotent: Ασφάλεια αναπαραγωγής.
• Συμβατή προς τα πίσω: εξέλιξη χωρίς «σπάσιμο» αλλαγών.
• Ακρόαση: κρυπτογραφικά επιβεβαιωμένα γεγονότα (αποδείξεις).

2) Σύμβαση και υποδείγματα (αναφορά)

OpenAPI για αιτήματα συγχρονισμού. AsyncAPI για εκδηλώσεις/webhooks.
Τα απαιτούμενα πεδία σε κάθε πόρο είναι 'id', 'version', 'created _ at', 'updated _ at', 'rentant', 'region', 'trace _ id'.

Παράδειγμα κατάτμησης σύμβασης

yaml paths:
/payments/payouts:
post:
operationId: createPayout requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutRequest'
responses:
"202": { $ref: '#/components/responses/AcceptedWithReceipt' }
headers:
Idempotency-Key:
schema: { type: string }
required: true components:
responses:
AcceptedWithReceipt:
description: Accepted, processing asynchronously headers:
Receipt-Hash: { schema: { type: string } }

3) Εξακρίβωση ταυτότητας, εξουσιοδότηση, πεδία εφαρμογής

για τους χρήστες/εταίρους - διαπιστευτήρια πελατών/JWT .
Πεδία/ρόλοι πόρων: "πληρωμές. γράψτε ',' καταλόγους. διάβασε «,» έλεγχος. εξαγωγή ".
ReBAC: πρόσβαση «κατά ιδιοκτησία» (ενοικιαστής/λογαριασμός/υπολογαριασμός).
Μυστικά JIT: βραχύβιες μάρκες, συσκευή/υποσύνολο/περιοχή σύνδεσης.
Στάση συσκευής & mTLS για κρίσιμες λειτουργίες (πληρωμές, κλειδιά).

4) Ταυτότητα και «ακριβώς μία φορά»

Idempotency-Key (κεφαλίδα) + dedup by '(κλειδί, λογαριασμός, διαδρομή)' στο παράθυρο TTL.
Outbox/CDC για την ανάρτηση εκδηλώσεων - εγγυημένη παράδοση.
Επακριβώς άπαξ επιδράσεις: οι παρενέργειες καταγράφονται μέσω ενός περιοδικού συναλλαγών. η επανάληψη οδηγεί στην ίδια «απόδειξη» («απόδειξη _ hash»).
Επαναπροσδιορισμός πολιτικών: εκθετική οπισθοδρόμηση, νευρικότητα, μέγιστα παράθυρα.

5) Όρια, ποσοστώσεις, ιεράρχηση προτεραιοτήτων

Όρια επιτοκίου: ανά κλειδί/ενοικιαστή/διαδρομή/περιφέρεια· «μαλακό» (429) και «σκληρό» (αποκοπή).
Ποσοστώσεις/προϋπολογισμοί: μηνιαία/ημερήσια ανώτατα όρια, webhook Ποσοστώσεις CapAched '.
Δίκαιη χρήση: προτεραιότητα των ενοικιαστών ανά επίπεδο υπηρεσίας (χρυσός/άργυρος/χαλκός).
Διαρρήξεις: σύντομες εκρήξεις χωρίς υποβάθμιση των γειτόνων.

6) Σελιδοποίηση, φίλτρα, δείγματα

Βασισμένο σε δρομείς (stable ordering по 'created _ at, id'), 'page _ size' ≤ 1000.
Δείγματα με φέτες χρόνου («από», «έως», «υδατογράφημα») για κορμούς/συναλλαγές.
Φιλτράρισμα DSL: whitelisted поля, '? status =... & penant =... & region =...'.
Υπαινιγμοί συνέπειας: 'snapshot _ a /' as _ of' για την αναφορά API.

7) Έκδοση και συμβατότητα

SemVer: 'v1', 'v1. 1 '(επεκτάσεις),' v2 '- μόνο σε νέες διαδρομές/χώρους ονομάτων.
Κανόνες εξέλιξης: προσθέστε μόνο πεδία/τιμές, «απορρίψτε → αφαιρέστε» από το παράθυρο.
Δοκιμές συμβατότητας: «προσομοιώσεις συμβάσεων» (με γνώμονα τον καταναλωτή).

8) Εκδηλώσεις, webhooks και αποδείξεις

Η AsyncAPI περιγράφει τα θέματα/ωφέλιμο φορτίο/υπογραφές.

Κεφαλίδα: HMAC/EdDSA, κεφαλίδες 'X-Signature', 'X-Nonce', 'X-Timestamp' (στενό παράθυρο)

Παραλαβές: «παραλαβή _ hash» και υπογραφή DSSE για κρίσιμα γεγονότα (πληρωμές, RTP/οριακές μεταβολές, καταλόγους τιμών).
Retrai και dedup: idempotency σύμφωνα με το 'idempotency _ key '/' event _ id'.
DLQ/καραντίνα: άκυρες/επαναλαμβανόμενες αναφορές με αίτια.

9) Παρατηρησιμότητα και ποιότητα

Ίχνη: υποχρεωτικό «trace _ id/span _ id» μέσω πύλης/επιχειρηματικών εκδηλώσεων/webhooks.
Μετρήσεις: διαθεσιμότητα, p50/p95/p99, ρυθμός σφάλματος, ρυθμός επαναδρομολόγησης, κόστος ανά 1k.
Αρχεία καταγραφής: δομημένα, χωρίς μυστικά/PII; 'tenant/region/version' labels.
SLO/ειδοποιήσεις: συνθήκες και αυτόματες διαδρομές με προσανατολισμό SLO (παύση/επαναδρομολόγηση/ανατροπή).

10) Σφάλματα και σημασιολογία κατάστασης

2xx - επιτυχία (202 για ασύγχρονες λειτουργίες).
4xx - σφάλμα πελάτη (422 - επικύρωση, 409 - σύγκρουση/ιδεατότητα, 429 - όρια).
5xx - προσωρινά προβλήματα.
Σφάλμα: 'code', 'message', 'trace _ id', 'int', 'retry _ after? '.
UX για τους εταίρους: πίνακας «τι να κάνετε» για κάθε σφάλμα.

11) Πολιτικές ως κώδικας (OPA/ABAC)

Κεντρική άδεια: «ποιος/τι/πού/πότε/γιατί».
Πολιτικές σε Git, αναθεώρηση κώδικα, δοκιμές ΚΚΠ (προ πτήσης: "θα επιτρέψει η πολιτική »).
Έλεγχος SoD: «δημιουργία πληρωμής» ≠ «έγκριση».

12) Ασφάλεια, ιδιωτικότητα, συμμόρφωση

ελαχιστοποίηση PII: μάσκες/μάσκες, πρόσβαση στο πρωτογενές μόνο μέσω εγκεκριμένων jabs.
Μυστικά: θησαυροφυλάκιο/KMS, σύντομο TTL, περιστροφές. απαγόρευση κοινών μυστικών.
Κρυπτογράφηση: mTLS/TLS 1. 3, AES-GCM σε ηρεμία, HSTS/PKP, κατά περίπτωση.
Γνώση δικαιοδοσίας - Εντοπισμός δεδομένων/κλειδιών ανά περιφέρεια.
Ημερολόγια ελέγχου: WORM, Merkle-φέτες, DSSE-υπογραφές.

13) Λειτουργία: SLI/SLO και ταμπλό

• Διαθεσιμότητα ανά διαδρομή/περιφέρεια.
• p95 καθυστέρηση (ανάγνωση/εγγραφή).
• Επιτυχία των webhooks (αποδείξεις), υστέρηση παράδοσης.
• Ποσοστό σφάλματος/ρυθμός επαναπροσδιορισμού.
• Κόστος ανά 1k αιτήσεων και έξοδος.

SLO (παράδειγμα): 99. 95% διαθεσιμότητα· p95 ≤ 120/250 ms· webhooks ≥ 99. 5 %/5-min· P1 MTTR ≤ 60 λεπτά.

14) Διαχείριση αλλαγών (Releases/Rollbacks)

Γαλάζιο-πράσινο/Κανάριος για πύλες και κρίσιμες διαδρομές.
Ficheflags για συμπεριφορά χωρίς απελευθέρωση.
για σχήματα και ωφέλιμο φορτίο.
: Rollback Release, Disable Flag, Re-route, Flush Cache.
Τεχνουργήματα: υπογεγραμμένες εικόνες/δηλωτικά, μητρώο έκδοσης.

15) SDK, πελάτες, αμμοκιβώτια

Επίσημα SDK (TS/Java/Python/Go) με το ίδιο σφάλμα και σημασιολογία retray.
Περιβάλλοντα sandbox με κλειδιά/πιστοποιητικά δοκιμής και προσομοιωτές PSP/KYC/παρόχου περιεχομένου.
Οι δοκιμές επί συμβάσει περιλαμβάνονται στο CI SDK, νυχτερινή συμβατότητα.

16) Υπόδειγμα δεδομένων (απλουστευμένο)

'api _ key' {id, ενοικιαστής, πεδία εφαρμογής [], ttl, created_by}'

'rate _ plan' {ενοικιαστής, quotas{route→cap}, διάρρηξη, προτεραιότητα} '

'request _ log' {trace _ id, route, actor, idempotency_key?, status, latency_ms, region, cost_unit}'

'webhook _ receipt' {event _ id, τελικό σημείο, κατάσταση, απόπειρες, receipt_hash, υπογραφή} '

'policy' '{έκδοση, κανόνες, υπογράφων, dsse}'

17) RACI

18) Μετρήσεις ποιότητας

Μετατόπιση συμβολαίου: 0 «σπάσιμο» αλλαγές χωρίς αποσύνθεση.
Ποσοστό σφάλματος ταυτότητας: ≤ 0. 01%.
Επιτυχία Webhook: ≥ 99. 5%, υστέρηση p95 ≤ 60 s.
Auth Fail vs Κατάχρηση: μερίδιο κακόβουλων μπλοκ, θόρυβος ≤ επίπεδο στόχου.
: έλεγχος μέσω διαδρομών και περιφερειών (προϋπολογισμοί/cap-alerts).
Υιοθέτηση SDK: μερίδιο της κυκλοφορίας μέσω επίσημων SDK.

19) Βιβλία αναπαραγωγής περιστατικών

Spike 429/όρια: αυξήστε το καπάκι για χρυσό, στραγγαλίζοντας «θορυβώδη» κλειδιά, σύνδεση με έναν σύντροφο.
Webh Lag: αύξηση εργαζομένων/παρτίδων, προτεραιότητα σε ουρές, προσωρινή απενεργοποίηση προαιρετικών webhooks.
Price Mismatch (κατάλογος/FX/Tax): συμφωνία έκδοσης, αναπηρία δύναμης κρυφής μνήμης, rollback τεχνουργήματος, αποζημίωση.
PSP Έξοδος: αλλαγή διαδρομής, καραντίνα των «γκρι» συναλλαγών, επανάληψη.
Συμβιβασμός API-κλειδί: άμεση ανάκληση, εναλλαγή, έλεγχος των τελευταίων 30 ημερών.

20) Ιδιαιτερότητα του iGaming/fintech

RTP/Όρια API: μόνο συγκεντρωτικά στοιχεία και εκδόσεις προφίλ· μεταβολές - με αποδείξεις.
Πληρωμές/πληρωμές: 202 + υπογεγραμμένα webhooks; Ιδιαιτερότητα κλειδιού παραγγελίας.
Θυγατρικές: μετατροπή dedup, εγγύηση για διαφορές, υπογεγραμμένες αναφορές.
Υπεύθυνο έργο: Εκθέστε «guardrails API» για όρια και εκδηλώσεις RG.

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

• Περιγραφόμενη σύμβαση (OpenAPI/AsyncAPI), επικύρωση CI και δοκιμές καταναλωτή.
• Ρυθμισμένα OAuth2/OIDC, πεδία εφαρμογής, μυστικά JIT και mTLS για κρίσιμες διαδρομές.
• Εισαγωγή idempotency, retrai, DLQ και καραντίνας.
• Ανώτατα όρια/ποσοστώσεις/προτεραιότητες και προειδοποιήσεις.
• Σελιδοποίηση δρομέα, 'as _ of' συνεπή δείγματα.
• Πολιτική έκδοσης και αποδυνάμωσης.
• Webhooks με υπογραφές/αποδείξεις, replay και dedup.
• Ίχνη/μετρήσεις/κούτσουρα, SLO και ρούνοι.

Κούτσουρα, υπογραφές DSSE, φέτες Merkle.

• SDK, αμμοκιβώτιο, προσομοιωτές, δείγματα κωδικών και πώς να.

22) ΣΥΧΝΈΣ ΕΡΩΤΉΣΕΙΣ

Γιατί 202 για μακροχρόνιες επιχειρήσεις

Για να μην κρατήσετε τη σύνδεση και να παράσχετε ένα αξιόπιστο retray/λήψη μέσω webhook.

Χρειάζεστε τόσο το OpenAPI όσο και το AsyncAPI

Ναι: συγχρονισμός εντολών/αιτημάτων, async για γεγονότα/κρατικές διαπραγματεύσεις.

Πώς να αποφευχθεί η διακοπή των αλλαγών

Κανόνας μόνο προσθήκης, απενεργοποίηση → παρατήρηση → αφαίρεση, σύμβαση δοκιμής πελάτη.

Πού να αποθηκεύσετε τις αποδείξεις

Σε ζώνη WORM με υπογραφές. Το 'receipt _ hash' επιστρέφεται στον πελάτη και ελέγχεται κατόπιν αιτήματος.

Περίληψη: Οι πράξεις μέσω API είναι η πειθαρχία της σύμβασης και της λειτουργίας: αυστηρό μοντέλο πρόσβασης και ταυτότητα, όρια και εκδόσεις, παρατηρησιμότητα και SLO, υπογραφές και παραλαβές. Προσθήκη αμμοκιβωτίων και SDK - και οι εταίροι θα ενσωματωθούν γρήγορα, με ασφάλεια και προβλέψιμο τρόπο, και οι επιχειρήσεις θα κλιμακωθούν χωρίς απώλεια ποιότητας ή συμμόρφωσης.