पारिस्थितिकी तंत्र एपीआई

(खंड: पारिस्थितिकी तंत्र और नेटवर्क)

1) लक्ष्य और सिद्धांत

• तेज, पूर्वानुमानित एकीकरण (समय-से-एकीकरण ↓)।
• विश्वसनीयता और स्केलेबिलिटी (एसएलओ, क्यूओएस, बैकप्रेशर)।
• सुरक्षा और अनुपालन (न्यूनतम अधिकार, लेखा परीक्षा)।
• ब्रेकडाउन के बिना विकास (संस्करण, संगतता, ficheflags)।

सिद्धांत: अनुबंध-प्रथम, डेटा न्यूनतम, पहचान, अवलोकन-दर-डिफ़ॉल्ट, रिलीज़ की "दो गति" (कोर बनाम प्रायोगिक)।

2) एपीआई टैक्सोनॉमी

1. REST/HTTP - तुल्यकालिक CRUD/कमांड ऑपरेशन, idempotency-key, pagination/cursors।

2. gRPC/QUIC - कम विलंबता, धाराएँ, द्विआधारी प्रोटोकॉल।

3. घटनाएँ (पब/सब) - डोमेन घटनाएँ ('जमा करें। ',' भुगतान। ',' पुल। ',' जोखिम। ').

4. वेबहुक - हस्ताक्षर और रिट्रे के साथ रिवर्स सूचनाएं।

5. GraphQL (सीमित) - एकत्रीकरण भौतिक स्टोरफ्रंट पर पढ़ ता है।

6. व्यवस्थापक/मेटा - निर्देशिका, संस्करण, स्थिति, कुंजी, कोटा।

पहुंच स्तर: सार्वजनिक (सीमित तरीके/पढ़ना), साथी (स्कोप और कोटा), आंतरिक (निजी आकृति)।

3) संविदा और योजनाएं

OpenAPI/AsyncAPI/Protobuf IDL सत्य का एकल स्रोत है।

डेटा अनुबंध - संगतता परीक्षण, सर्किट लिंटर्स, मेजर के बिना "ब्रेकिंग" क्षेत्रों का निषेध।

कैटलॉग: संपत्ति/नेटवर्क, पीएसपी/विधियाँ, क्षेत्र/न्यायालय, एसडीके संस्करण, क्षमता झंडे।

न्यूनतम REST अनुबंध (OpenAPI टुकड़ा)

yaml openapi: 3. 0. 3 info: { title: Ecosystem Core API, version: "2. 6. 0" }
paths:
/v2/payouts:
post:
operationId: createPayout parameters:
- in: header name: Idempotency-Key required: true schema: { type: string, maxLength: 64 }
requestBody:
required: true content:
application/json:
schema:
$ref: "#/components/schemas/PayoutRequest"
responses:
"202": { $ref: "#/components/responses/Ack" }
"409": { description: "Duplicate (idempotent)" }
components:
schemas:
PayoutRequest:
type: object required: [amount, currency, destination]
properties:
amount:  { type: string, pattern: "^[0-9]+(\\.[0-9]{1,9})?$" }
currency: { type: string, example: "USD" }
destination: { type: string }
metadata: { type: object, additionalProperties: true }

घटनाएँ (AsyncAPI)

yaml asyncapi: 2. 6. 0 info: { title: Ecosystem Events, version: "1. 9. 0" }
channels:
payout. finalized:
subscribe:
message:
name: PayoutFinalized payload:
type: object required: [id, ts, amount, currency, status, signature]
properties:
id: { type: string }
ts: { type: string, format: date-time }
amount: { type: string }
currency: { type: string }
status: { type: string, enum: ["finalized","failed"] }
signature: {type: string} # source signature

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

SemVer: 'मेजर। माइनर। PATCH '। MINTER/PATCH - पिछड़े-संगत; मेजर - समानांतर संस्करण ('/v1 ', '/v2') + एडाप्टर।

अस्वीकृति नीति: खिड़की ≥ 90 दिन, समर्थन की "दो पंक्तियाँ", अनुबंध के लिए स्वचालित सूचनाएं।

फ्लैग्स: क्षेत्र/भागीदार द्वारा फ़ील्ड/विधियाँ सक्षम/अक्षम करें।

क्षमता बातचीत: हाथ मिलाते समय समर्थित प्रोफाइल की घोषणा।

5) पहचान, आदेश और संकेतक

कमांड के लिए Idempotency-Key (बनाएँ/रद्द करें), TTL कुंजी ≥ 72 घंटे.

आउटबॉक्स/इनबॉक्स और आइडेम्पोटेंट उपभोक्ता के माध्यम से बिल्कुल एक बार शब्दार्थ।

संकेतकों द्वारा पृष्ठभूमि: 'अगला _ कर्सर', सम्मिलन/विलोपन का प्रतिरोध।

छंटाई और फिल्टर स्थिर हैं, स्पष्ट रूप से प्रलेखित हैं।

6) सुरक्षा और विश्वास

mTLS (service↔service), सर्ट का पिनिंग और कुंजी रोटेशन।

OAuth2/OIDC (क्लाइंट क्रेडेंशियल्स, शॉर्ट टीटीएल के साथ जेडब्ल्यूटी), चैनल के लिए बाध्यकारी के लिए पीओपी/डीपीओपी।

वेबहुक हस्ताक्षर (NMAS/कुंजी संस्करण/समय), पुनरावृत्ति सुरक्षा।

RBAC/ABAC और PoLP: स्कोप, org_id/tenant_id, ऑब्जेक्ट/ऑपरेशन पर सीमा।

डीएलपी/पीआईआई न्यूनतम करना: लेबल/लॉग में पीआईआई निषेध, पहचानकर्ताओं का टोकन।

दर-सीमा और WAF: प्रति org/मार्ग/क्षेत्र, दुरुपयोग संरक्षण।

नमूना कुंजी नीति (YAML)

yaml auth:
oauth2:
issuer: "https://auth. ecosys"
jwks_uri: "https://auth. ecosys/.well-known/jwks. json"
token_ttl_s: 900 mtls:
required_for: ["internal","partner_p0"]
scopes:
- name: payouts:write
- name: payouts:read
- name: events:subscribe

7) कोटा, QoS और बैकप्रेशर

QoS कक्षाएं: P0 (भुगतान/पुल/अंतिम रूप), P1 (उत्पाद), P2 (थोक/संग्रह)।

कोटा/सीमाएं: आरपीएस, कॉन्सर-अनुरोध, बाइट्स/सेकंड, विषय/पार्टी के लिए।

प्रवेश नियंत्रण: "महंगे" अनुरोधों की प्रारंभिक अस्वीकृति, भारी-क्वेरी-गार्ड।

बैकप्रेशर: टोकन/क्रेडिट, डीएलक्यू के साथ कतारें, जिटर के साथ पीछे हटना।

कोटा नीति

yaml quotas:
partner_default:
rps: 200 concurrent: 100 webhooks_outbound_rps: 50 p0:
rps: 100 p95_latency_ms: 400

8) अवलोकन: SLI/SLO, मैट्रिक्स, निशान

• p95/99 लेटेंसी по маршрутам, सक्सेस रेट, एरर बजट बर्न, क्यू-लैग पी 95, फ्रेशनेस वेबहुक, डिलीवरी सफलता%।
• अनुबंध अनुपालन% (स्कीमा/हस्ताक्षर)।
• वेबहुक रीट्री/ड्रॉप%।

SLO: P0 p95 ≤ 400 ms, उपलब्धता ≥ 99। 95%; वेबहुक डिलीवरी p95 ≤ 2 с; घटनाओं की ताजगी p95 ≤ 60 с।

मेट्रिक्स: विलंबता हिस्टोग्राम, त्रुटि कोड, प्रतिक्रियाओं का आकार, आरपीएस, प्रति-किरायेदार।

ट्रेस: end-to-end 'trace _ id' (edge→gateway→service→DB→event/webhook)।

लॉग: संरचित, पीआईआई के बिना, 'अनुरोध _ आईडी' द्वारा सहसंबंध।

9) डाउनटाइम-फ्री रिलीज पैटर्न

एसएलओ द्वार और बाहरी-इजेक्शन के साथ ब्लू-ग्रीन/कैनरी।

स्कीमा-प्रथम विकास: केवल क्षेत्रों को जोड़ ना, पुराने ग्राहकों के लिए एडेप्टर।

शून्य-डाउनटाइम डेटाबेस माइग्रेशन: ऑनलाइन डीडीएल, द्विदिश कन्वर्टर्स।

नियंत्रण बदलें: टाइमलॉक, ऑडिट और संगतता रजिस्ट्री।

10) कैटलॉग और रजिस्टर

एपीआई/संस्करण रजिस्टर

sql
CREATE TABLE api_registry(
name TEXT, kind TEXT,      -- rest    grpc    events    webhook version TEXT, status TEXT,   -- active    canary    deprecated    retired slo JSONB, owner TEXT,
PRIMARY KEY (name, version)
);

घटना कैटलॉग

sql
CREATE TABLE event_catalog(
topic TEXT PRIMARY KEY,
schema_version TEXT,
qos TEXT,
retention_days INT,
pii BOOLEAN DEFAULT false
);

कुंजी/स्कोप

sql
CREATE TABLE api_keys(
key_id TEXT PRIMARY KEY,
org_id TEXT, scopes TEXT[], status TEXT, expires_at TIMESTAMPTZ
);

11) अनुबंधों का परीक्षण और अनुपालन

अनुबंध-परीक्षण: ग्राहक पीढ़ी, स्कीमा सत्यापन, negative-_cases।

पुनरावृत्ति घटना परीक्षण: पुनरावृत्ति/पुनर्व्यवस्था का प्रतिरोध।

अराजकता/लाट-परीक्षण: नुकसान/जिटर इंजेक्शन, धीमा स्टोर।

सुरक्षा-परीक्षण: वेबहुक हस्ताक्षर, कुंजी रोटेशन, फिर से हमले।

प्रदर्शन प्रोफाइल: एसएलए स्पाइक्स, गर्म मार्ग, डीए/निर्भरता पुल।

12) इंटरफेस के उदाहरण

वेबहूक (हस्ताक्षर और रेट्राई)

yaml webhooks:
deliveries:
retry:
attempts: 5 backoff_ms: [200, 800, 1600, 3200, 6400]
jitter: true signature:
alg: "HMAC-SHA256"
header: "X-ECO-Signature"
timestamp_header: "X-ECO-Timestamp"
tolerance_s: 300

ग्राफ़क्यूएल (एग्रीगेटिंग रीड्स, केवल पढ़ें)

graphql type Query {
payouts(status: [Status!], first: Int!, after: String): PayoutConnection!
}

जीआरपीसी (घटना प्रवाह)

proto service EventStream {
rpc Subscribe(SubscribeRequest) returns (stream Event);
}

13) प्रक्रियाएं और भूमिकाएँ

एपीआई मालिक - संविदा/संस्करण/एसएलओ/कोटा।

सुरक्षा - कुंजी/हस्ताक्षर/ऑडिट/डीएलपी।

एसआरई/ऑप्स - डैशबोर्ड, अलर्ट, क्षमता।

पार्टनर सक्सेस - ऑनबोर्डिंग, लिमिट, फिचफ्लैग्स।

अनुपालन - न्यायालय, प्रतिबंध, रिपोर्टिंग।

14) डैशबोर्ड

कोर एपीआई: मार्ग और तम्बू द्वारा विलंबता/त्रुटि/आरपीएस।

वेबहूक: डिलीवरी p95, रेट्रीज़, ड्रॉप्स, सिग्नेचर।

घटनाएँ: ताजगी, अंतराल, उपभोक्ता स्वास्थ्य, डीएलक्यू।

सुरक्षा: समाप्ति कुंजी, हस्ताक्षर, निवेदन अस्वीकृत.

शासन: सक्रिय संस्करण/मूल्यह्रास, अनुबंध संगतता।

15) प्लेबुक की घटनाएं

ए। p95 विलंबता P0 की वृद्धि

1. P0 और P2-throttle प्राथमिकता सक्षम करें; 2) स्केल गेटवे;

2. "हॉट" मार्गों के कैश 4) विश्लेषण के लिए रीड का हिस्सा स्विच करें।

बी। डिलीवरी वेबहुक ड्रॉप

1. हस्ताक्षर/घंटा शिफ्ट, 2) रेट्रे/टाइमआउट बढ़ाएँ,

2. बैचों को चालू करें, 4) अस्थायी रूप से बुलेट एंडपॉइंट पर स्विच करें।

सी। बहाव अनुबंध

1. "सख्त मोड" सक्षम करें,

2. निर्माता को सूचित करें, 3) एडाप्टर जारी करें, 4) पोस्टमार्टम, लिंटर्स को अपडेट करें।

डी। कुंजी/प्रमाणित समझौता

1. रेवोक/रोटेट, 2) रीप्ले वेबहूक, 3) ऑडिट, 4) भागीदारों को सूचित करें।

ई। दोहराएं/विस्फोट लें

1. Idempotency-Key/TTL, 2) डेडअप को मजबूत करें, 3) "शोर" स्रोत को सीमित करें।

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

1. वर्णन अनुबंध (OpenAPI/AsyncAPI/IDL), लिंटर और CI शामिल हैं।

2. कॉन्फ़िगर करें (OAuth2/OIDC, mTLS), वेबहुक हस्ताक्षर, कुंजी घुमाव।

3. कोटा/QoS/लिमिट, हैवी-क्वेरी-गार्ड और बैकप्रेशर भरें।

4. अवलोकन बढ़ाएं: SLI/SLO, ट्रैक, डैशबोर्ड, अलर्ट।

5. व्यवस्थित रिलीज़: कैनरी/ब्लू-ग्रीन, स्कीमा-फर्स्ट माइग्रेशन।

6. संस्करण/घटना/कुंजी निर्देशिका तथा पदावनत प्रक्रियाएँ प्रारंभ करें।

7. अराजकता/पर्फ/सुरक्षा परीक्षण करें, प्लेबुक की व्यवस्था करें।

8. नियमित रूप से डेटा न्यूनतम और नियामक अनुपालन को सुधारें।

17) शब्दावली

अनुबंध-पहला - कोड के लिए औपचारिक अनुबंध के माध्यम से एपीआई डिजाइन।

Idempotency-Key - एक कुंजी जो ऑपरेशन को सुरक्षित रूप से दोहराती है।

AsyncAPI - घटना इंटरफेस का विनिर्देशन।

QoS - सेवा की गुणवत्ता/प्राथमिकता वर्ग।

DLQ - समस्या संदेश के लिए "मृत कतार"।

त्रुटि बजट बर्न - SLO के सापेक्ष त्रुटि बजट "बर्निंग" की दर।

नीचे की रेखा: पारिस्थितिकी तंत्र एपीआई समापन बिंदुओं का एक सेट नहीं है, लेकिन अनुबंध, सुरक्षा, कोटा और अवलोकन की एक प्रबंधित प्रणाली है। इस ढांचे का पालन करके, पारिस्थितिकी तंत्र तेजी से एकीकरण, पूर्वानुमानित एसएलओ और डाउनटाइम के बिना सुरक्षित विकास प्राप्त करता है - नेटवर्क परत और प्रमाणीकरण से घटना प्रवाह और रिपोर्टिंग तक।