एपीआई संचालन

(धारा: संचालन और प्रबंधन)

1) उद्देश्य और सिद्धांत

एपीआई पारिस्थितिकी तंत्र की "परिचालन परत" है: अनुबंध के माध्यम से स्वचालित कुछ भी मैनुअल काम और जोखिम में नहीं बदल जाता है।

• अनुबंध-पहला: पहला विनिर्देश (OpenAPI/JSON स्कीमा/AsyncAPI), फिर कार्यान्वयन।
• सुरक्षित-दर-डिफ़ॉल्ट: न्यूनतम स्कोप, छोटा टीटीएल, आपसी-टीएलएस/हस्ताक्षर।
• अवलोकन योग्य: एंड-टू-एंड ट्रेसिंग और एसएलए मैट्रिक्स।
• पहचान: फिर से सुरक्षित।
• बैकवर्ड-संगत: "ब्रेकिंग" परिवर्तन के बिना विकास।
• श्रव्य: क्रिप्टोग्राफिक रूप से पुष्ट तथ्य (प्राप्तियां)।

2) अनुबंध और मॉडल (संदर्भ)

समन्वयन निवेदन के लिए OpENI; घटनाओं/वेबहूक के लिए AsyncAPI।

प्रत्येक संसाधन में आवश्यक क्षेत्र 'आईडी', 'संस्करण', 'निर्मित _ at', 'अद्यतन _ at', 'किरायेदार', 'क्षेत्र', 'ट्रेस _ आईडी' हैं।

अनुबंध के टुकड़े का उदाहरण

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 रहस्य: अल्पकालिक टोकन, उपकरण/सबनेट/क्षेत्र बाध्यकारी।

महत्वपूर्ण संचालन (भुगतान, कुंजी) के लिए उपकरण आसन और एमटीएलएस।

4) पहचान और "बिल्कुल एक बार"

Idempotency-Key (शीर्षक) + dedup '(कुंजी, खाता, मार्ग)' TTL विंडो पर.

घटनाओं की गारंटी प्रदान करने के लिए आउटबॉक्स/सीडीसी।

वास्तव में एक बार-प्रभाव: दुष्प्रभाव एक लेनदेन पत्रिका के माध्यम से कब्जा कर लि पुनरावृत्ति एक ही "रसीद" ('रसीद _ हैश') की ओर जाता है।

पुनः प्रयास नीतियां: घातीय बैक-ऑफ, जिटर, अधिकतम खिड़कियां।

5) सीमाएं, कोटा, प्राथमिकता

दर सीमा: प्रति-कुंजी/किरायेदार/मार्ग/क्षेत्र; "सॉफ्ट" (429) और "हार्ड" (कटऑफ)।

कोटा/बजट: मासिक/दैनिक कैप, वेबहूक 'कोटा कैपेस्टेड'।

निष्पक्ष उपयोग: सेवा स्तर (स्वर्ण/रजत/कांस्य) द्वारा किरायेदारों की प्राथमिकता।

फट बफर्स: पड़ोसियों के क्षरण के बिना छोटा फटता है।

6) पैगिनेशन, फिल्टर, नमूने

कर्सर-आधारित (स्थिर ऑर्डरिंग по 'निर्मित _ at, id'), 'पृष्ठ _ आकार' ≤ 1000।

लॉग/लेनदेन के लिए समय-कटा हुआ नमूना ('से', 'से', 'वॉटरमार्क')।

फ़िल्टरिंग DSL: सफेदी की गई поля, '? स्थिति =... & किरायेदार =... & क्षेत्र =...'।

संगति संकेत: एपीआई की रिपोर्टिंग के लिए 'स्नैपशॉट _ at '/' as _ of'।

7) वर्शनिंग और संगतता

SemVer: 'v1', 'v1। 1 '(एक्सटेंशन),' v2 '- केवल नए रास्तों/नेमस्पेस पर।

एवोल्यूशन नियम: सिर्फ क्षेत्र/मान जोड़ें, विंडो के माध्यम से "deprecate → हटाएँ".

संगतता परीक्षण: "अनुबंध-के-परीक्षण" (उपभोक्ता-चालित)।

8) घटनाएँ, वेबहूक और प्राप्तियाँ

AsyncAPI थीम/पेलोड/हस्ताक्षर का वर्णन करता है।

कैप्शन: HMAC/EdDSA, हेडर 'X-Signature', 'X-Nonce', 'X-Timestamp' (संकीर्ण विंडो)

रसीदें: महत्वपूर्ण घटनाओं (भुगतान, आरटीपी/सीमा परिवर्तन, मूल्य सूची) पर 'रसीद _ हैश' और डीएसएसई हस्ताक्षर।

Retrai और dedup: 'idempotency _ key '/' event _ id' के अनुसार पहचान।

DLQ/संगरोध: कारणों के साथ अवैध/बार-बार रिपोर्ट।

9) अवलोकन और गुणवत्ता

ट्रेस: गेटवे/बिजनेस इवेंट्स/वेबहूक के माध्यम से अनिवार्य 'ट्रेस _ आईडी/स्पैन _ आईडी'।

मेट्रिक्स: उपलब्धता, p50/p95/p99, त्रुटि-दर, पुनरावृत्ति-दर, लागत प्रति 1k।

लॉग: संरचित, कोई रहस्य/पीआईआई नहीं; 'किरायेदार/क्षेत्र/संस्करण' लाबल्स।

SLO/अलर्ट: SLO-उन्मुख स्थिति और ऑटो-रनर (ठहराव/पुन: मार्ग/रोलबैक)।

10) त्रुटियां और स्थिति शब्दार्थ

2xx - सफलता (अतुल्यकालिक संचालन के लिए 202)।

4xx - क्लाइंट की गलती (422 - सत्यापन, 409 - संघर्ष/पहचान, 429 - सीमा)।

5xx - अस्थायी समस्याएं।

त्रुटि निकाय: 'कोड', 'संदेश', 'ट्रेस _ आईडी', 'संकेत', 'रीट्री _ आफ्टर? '.

भागीदारों के लिए UX: प्रत्येक त्रुटि के लिए "क्या करना है" की एक तालिका।

11) नीतियां-जैसे-कोड (OPA/ABAC)

केंद्रीकृत प्राधिकरण: "कौन/क्या/कहाँ/कब/क्यों"।

गिट में नीतियां, कोड समीक्षा, सीआई परीक्षण (पूर्व उड़ान: "क्या नीति की अनुमति दी जाएगी? »).

SoD जाँच: "भुगतान बनाएं" ≠ "अनुमोदित करें।"

12) सुरक्षा, गोपनीयता, अनुपालन

पीआईआई कम से कम: टोकन/मास्क, केवल अनुमोदित जैब के माध्यम से प्राथमिक तक पहुंच।

रहस्य: तिजोरी/केएमएस, लघु टीटीएल, घुमाव; साझा रहस्यों का निषेध।

एनक्रिप्शन: mTLS/TLS 1। 3, एईएस-जीसीएम एट-रेस्ट, एचएसटीएस/पीकेपी जहां उपयुक्त हो।

अधिकार क्षेत्र-जागरूक - प्रति क्षेत्र डेटा/कुंजियों का स्थानीयकरण।

ऑडिट लॉग: WORM, मर्कल-स्लाइस, DSSE-हस्ताक्षर।

13) ऑपरेशन: SLI/SLO और डैशबोर्ड

• प्रति मार्ग/क्षेत्र की उपलब्धता।
• p95 विलंबता (पढ़ें/लिखें)।
• वेबहुक (प्राप्तियों) की सफलता, वितरण अंतराल।
• त्रुटि-दर/रीट्री-दर।
• प्रति 1k अनुरोध और egress लागत।

एसएलओ (उदाहरण): 99। 95% उपलब्धता; p95 ≤ 120/250 ms; वेबहूक ≥ 99। 5 %/5-मिनट; P1 MTTR ≤ 60 मिनट।

14) परिवर्तन प्रबंधन (रिलीज/रोलबैक)

गेटवे और महत्वपूर्ण मार्गों के लिए ब्लू-ग्रीन/कैनरी।

नो-रिलीज व्यवहार के लिए Ficheflags।

Expand→Migrate→Contract स्कीमा और पेलोड के लिए।

Руны: रोलबैक रिलीज, डिसेबल फ्लैग, री-रूट, फ्लश कैश।

कलाकृतियाँ: हस्ताक्षरित चित्र/प्रकट, संस्करण रजिस्ट्री।

15) एसडीके, क्लाइंट, सैंडबॉक्स

आधिकारिक एसडीके (टीएस/जावा/पायथन/गो) एक ही त्रुटि और रिट्रे शब्दार्थ के साथ।

परीक्षण कुंजी/प्रमाणपत्र और PSP/KYC/सामग्री प्रदाता सिमुलेटर के साथ सैंडबॉक्स वातावरण।

अनुबंध-परीक्षण CI SDK में शामिल हैं, रात की संगतता।

16) डेटा मॉडल (सरलीकृत)

'api _ key' {id, किरायेदार, स्कोप्स [], ttl, created_by}'

'rate _ plan' '{किरायेदार, quotas{route→cap}, फट, प्राथमिकता}'

'request _ log' '{trace _ id, मार्ग, अभिनेता, idempotency_key?, स्थिति, latency_ms, क्षेत्र, cost_unit}'

'वेबहुक _ रसीद' '{event _ id, समापन बिंदु, स्थिति, प्रयास, receipt_hash, हस्ताक्षर}'

'पोलिसी' {संस्करण, नियम, हस्ताक्षरकर्ता, dsse} '

17) आरएसीआई

18) गुणवत्ता मैट्रिक्स

अनुबंध बहाव: 0 "ब्रेकिंग" बिना मूल्यह्रास के परिवर्तन।

पहचान त्रुटि दर: ≤ 0। 01%.

वेबहुक सफलता: ≥ 99। 5%, अंतराल p95 ≤ 60 s।

औथ फेल बनाम दुर्व्यवहार: दुर्भावनापूर्ण ब्लॉकों का हिस्सा, शोर - लक्ष्य स्तर।

Cost/1k: मार्गों और क्षेत्रों (बजट/कैप-अलर्ट) द्वारा नियंत्रण।

दत्तक एसडीके: आधिकारिक एसडीके के माध्यम से यातायात का हिस्सा।

19) हादसा प्लेबुक

स्पाइक 429/सीमाएं: गोल्ड के लिए कैप बढ़ाएं, "शोर" कुंजियों को थ्रॉटलिंग, एक साथी के साथ कनेक्शन।

WebhookLag: श्रमिकों/बैचों को बढ़ाएं, कतारों को प्राथमिकता दें, अस्थायी रूप से वैकल्पिक वेबहूक बंद करें।

प्राइसमिसमैच (कैटलॉग/एफएक्स/टैक्स): संस्करण सामंजस्य, कैश बल विकलांगता, कलाकृति रोलबैक, मुआवजा।

PSP आउटेज: रूट स्विचिंग, "ग्रे" लेनदेन का संगरोध, रीप्ले।

एपीआई-की से समझौता करें: पिछले 30 दिनों का तत्काल रिकॉल, रोटेशन, ऑडिट।

20) iGaming/fintech की विशिष्टता

RTP/लिमिट API: केवल समुच्चय और प्रोफ़ाइल संस्करण; परिवर्तन - रसीदों के साथ।

भुगतान/भुगतान: 202 + हस्ताक्षरित वेबहूक; आदेश कुंजी पहचान।

सहयोगी: रूपांतरण डीडअप, विवादों के लिए एस्क्रो, हस्ताक्षरित रिपोर्ट।

जिम्मेदार नाटक: सीमा और आरजी घटनाओं के लिए "रेलिंग एपीआई" को उजागर करें।

21) कार्यान्वयन चेकलिस्ट

• वर्णित अनुबंध (OpenAPI/AsyncAPI), CI सत्यापन और उपभोक्ता-परीक्षण।
• महत्वपूर्ण मार्गों के लिए कॉन्फ़िगर -, स्कोप, जेआईटी रहस्य और एमटीएलएस।
• आइडेम्पोटेंसी, रेट्राई, डीएलक्यू और संगरोध पेश किया।
• कैप्स/कोटा/प्राथमिकताएं और अलर्ट।
• कर्सर पगिनेशन, 'के रूप में _' सुसंगत नमूने।
• सत्यापन और मूल्यह्रास नीति।
• हस्ताक्षर/रसीदें, रीप्ले और डेडअप के साथ वेबहुक।
• ट्रेस/मेट्रिक्स/लॉग, एसएलओ और रन।
• WORM लॉग, DSSE हस्ताक्षर, मर्कल स्लाइस।
• एसडीके, सैंडबॉक्स, सिमुलेटर, कोड नमूने और कैसे-कैसे।

22) FAQ

लंबे ऑपरेशन के लिए 202 क्यों?

कनेक्शन न रखने और वेबहुक के माध्यम से एक विश्वसनीय रिट्रे/रसीद प्रदान करने के लिए।

क्या आपको OpenAPI और AsyncAPI दोनों की आवश्यकता है?

हां: कमांड/अनुरोध के लिए सिंक करें, घटनाओं/राज्य वार्ता के लिए अतुल्य।

परिवर्तनों को तोड़ ने से कैसे बचें

ऐड-ओनली नियम, पदावनत → निरीक्षण करें → हटाएं, ग्राहक परीक्षण अनुबंध।

रसीदें कहां जमा करें?

हस्ताक्षर के साथ एक WORM क्षेत्र में; 'receipt _ hash' ग्राहक को लौटा दिया जाता है और अनुरोध पर जाँच की जाती है।

सारांश: एपीआई के माध्यम से संचालन अनुबंध और संचालन का अनुशासन है: सख्त पहुंच मॉडल और पहचान, सीमा और संस्करण, अवलोकन और एसएलओ, हस्ताक्षर और प्राप्तियां। सैंडबॉक्स और एसडीके जोड़ें - और भागीदार जल्दी से, सुरक्षित और अनुमानित रूप से एकीकृत होंगे, और व्यवसाय गुणवत्ता या अनुपालन के नुकसान के बिना पैमाने पर होंगे।