एपीआई अस्तर और स्थिर विश्लेषण

1) एपीआई को क्यों लिंक करें

• असंगत और अंतर्निहित परिवर्तनों को रोकें
• स्टेटस, त्रुटियों, पृष्ठभूमि, सुरक्षा को एकजुट करें;
• विनिर्देशों को मशीन-सत्यापन योग्य बनाएं और अनुमानित जारी करें;
• समीक्षा और ऑनबोर्डिंग समय की लागत को कम करें।

सिद्धांत: "अनुबंधों को स्वचालित रूप से जांचा जाता है; हरे रंग की लिंटिंग के बिना पीआर पकड़ नहीं रखता है।"

2) लिंटिंग सुविधाएं

1. अनुबंध: OpenAPI/AsyncAPI/GraphQL SDL, Protobuf/Avro/JSON स्कीमा।

2. कार्यान्वयन: REST/gRPC पेन, मिडिलवेयर, स्थिति कोड/हेडर।

3. बुनियादी ढांचा: सुरक्षा हेडर, सीमा, कैश नीतियां।

4. संबंधित कलाकृतियाँ: उदाहरण, पोस्टमैन संग्रह, त्रुटि योजनाएं।

3) HTTP API के लिए मूल नियम (अनुशंसित प्रोफ़ाइल)

3. 1 संकेतन और यूआरएल

snake_case JSON निकायों में, रास्तों में कबाब-मामला, या वर्दी कबाब-केस/'/v1/... '.

संसाधन - बहुवचन: '/v1/भुगतान ', नेस्टेड - '/v1/वॉलेट/{ id }/लेनदेन'।

path-params के रूप में पहचानकर्ता: '/v1/भुगतान/{ pament _ id} '(प्रकार: string, प्रारूप: uuid)।

3. 2 तरीके और स्थितियाँ

'गेट' - 200/206; ' POST '- 201 (+' स्थान '), विरोधाभास - 409; सत्यापन - 422; सीमा - 429 (+ 'रीट्री-आफ्टर')।

त्रुटियों के लिए 200 वापस न करें. सशर्त प्रश्न - 'इफ-नो-मैच' द्वारा 304।

3. 3 त्रुटियाँ (एकल प्रारूप)

json
{ "code":"validation_error", "message":"amount must be ≥ 1", "trace_id":"...", "details":[{"field":"amount","reason":"min:1"}] }

आवश्यक: 'कोड', 'संदेश', 'ट्रेस _ आईडी'; लोकेल - 'कंटेंट-लैंग्वेज' के माध्यम से।

3. 4 पैगिनेशन/फ़िल्टर

संकेतक आधारित: 'पृष्ठ _ आकार', 'पृष्ठ _ टोकन', ответ: 'अगला _ पृष्ठ _ टोकन'.

फिल्टर और सॉर्टिंग - व्हाइटलिस्ट 'पैरामीटर' में प्रलेखित।

3. 5 सुरक्षा

वर्दी सुरक्षा योजना: OAuth2/OIDC स्कोप या एमटीएलएस; 'http' (केवल 'https') से इनकार करें।

संवेदनशील शीर्षिका नहीं लौटाएँ, उदाहरणों में मुखौटा टोकन.

3. 6 सीमाएँ और आयाम

शीर्षक/शरीर की सीमा: 413/414/431; दस्तावेज़ अधिकतम स्वीकृत मान।

4) उपकरण और पारिस्थितिकी तंत्र

4. 1 OpenAPI

स्पेक्ट्रल (JSON/YAML लिंट), Redocly linter, oas-diff/openapi-diff (सिमेंटिक डिफ), स्कीमैथिसिस/ड्रेड (प्रगति में जांच)।

4. 2 प्रोटोबुफ/जीआरपीसी

बफ (लिंट + ब्रेकिंग चेक), प्रोटोलिंट, एसडीके जनरेटर; विश्लेषण के लिए ज्ञानी।

4. 3 ग्राफ़क्यूएल

ग्राफकल-स्कीमा-लिंटर, ग्राफकल-इंस्पेक्टर (ब्रेकिंग)।

4. 4 कोड लिंटर्स और SAST

ESLint, golangci-lint, Detekt/Ktlint, Pylint/Flake8, Semgrep (API गंध और सुरक्षा टेम्पलेट)।

5) नियम उदाहरण: वर्णक्रमीय/Redocly

5. 1 वर्णक्रमीय (उदाहरण 'वर्णक्रमीय। yaml ')

yaml extends: ["spectral:oas", "spectral:asyncapi"]
rules:
openapi-tags: off info-contact: error no-http: error path-kebab-case:
description: "Paths must be kebab-case"
given: "$.paths[]~"
severity: error then:
function: pattern functionOptions: { match: "^/(?:[a-z0-9]+(?--[a-z0-9]+)/?)+$" }
response-error-schema:
description: "Error responses must use standard schema"
given: "$.paths[][].responses[?(@property >= '400')]"
then:
field: "content.application/json.schema.$ref"
function: truthy id-as-uuid:
given: "$..parameters[?(@.name =~ /.id$/i)]"
then:
field: schema.format function: enumeration functionOptions: { values: ["uuid"] }

5. 2 Redocly (टुकड़ा '.redocly। yaml ')

yaml apis:
main: openapi.yaml lint:
extends:
- recommended rules:
no-ambiguous-paths: error operation-2xx-only: off operation-success-response:
severity: error where:
subject: response filterInParentKeys: ["200","201","204"]
operation-security-defined: error no-plain-http: error

6) प्रोटोबुफ/जीआरपीसी: बफ प्रोफाइल

6. 1 'बफ। yaml '

yaml version: v2 modules:
- path: proto lint:
use:
- DEFAULT except:
- PACKAGE_VERSION_SUFFIX # используем v1 в package breaking:
use:
- WIRE_JSON deps: []

• फ़ील्ड संख्याओं का पुनः उपयोग न करें; हटाया - 'आरक्षित'।
• नए क्षेत्र - 'वैकल्पिक' या डिफ़ॉल्ट के साथ; प्रकार/शब्दार्थ न बदलें।

7) सिमेंटिक डिफ और "ब्रेकिंग" परिवर्तन

7. 1 HTTP

• फ़ील्ड क़िस्म/अनिवार्य बदलें
• स्थिति/मार्ग/पैरामीटर मिटाएँ
• एनम/रेंज संकीर्ण;
• आईडी (uuid → string) प्रारूप का परिवर्तन।

• वैकल्पिक क्षेत्र जोड़
• नई स्थिति जो खुश पथ को प्रभावित नहीं करती है (उदाहरण के लिए, प्रलेखित '422')
• enum विस्तार।

7. 2 जीआरपीसी/प्रोटोबुफ

'आरक्षित '/पुनर्निर्मित किए बिना एक क्षेत्र को हटाना।

टाइप बदलें (int32 → string) - ब्रेकिंग।

वैकल्पिक के रूप में एक नया टैग जोड़ ना आमतौर पर सुरक्षित है।

8) संविदा और कोड लिंकिंग

1. अनुबंध → कोड: एसडीके/सर्वर स्टब्स की पीढ़ी, परीक्षणों में नकारात्मक उदाहरण।

2. अनुबंध → कोड: विनिर्देशन परीक्षण, स्टेटस/हेडर की स्वचालित जांच।

• अस्वीकार करना '200' when 'error! = nil';
• भुगतान मार्गों पर अनिवार्य 'आइडेम्पोटेंसी-की';
• लॉग में मास्किंग टोकन।

9) सीआई/सीडी पाइपलाइन (संदर्भ)

pre-commit: spectral lint, redocly lint
PR gate:  openapi-diff (base..PR), buf breaking-check, graphql-inspector build:   schemathesis smoke, unit/integration linters (ESLint/golangci-lint)
release:  publish contracts (artifact/broker), sign & tag

• ब्रेकिंग-डिफ़है;
• बुनियादी नियमों का उल्लंघन किया गया है (स्थिति/सुरक्षा/त्रुटियां)
• मापदंडों के कोई उदाहरण/विवरण नहीं हैं।

10) नियम कैटलॉग (आपके संगठन के लिए टेम्पलेट)

पहचानकर्ता और प्रकार

'_ id' - 'स्ट्रिंग', 'प्रारूप: uuid'।

मुद्रा क्षेत्र - स्केल के साथ 'स्ट्रिंग '/' दशमलव'; मुद्रा - ISO-4217।

गलतियाँ

एकीकृत योजना (देखें) 3। 3), कोड: '400/401/403/404/409/422/429/5xx'।

हमेशा 'ट्रेस _ id'; ' रेट्री-आफ्टर 'फोर 429/503।

पृष्ठभूमि

केवल संकेतक; अधिकतम 'पृष्ठ _ आकार' प्रलेखित।

सुरक्षा

सभी ऑपरेशन - 'सुरक्षा' ब्लॉक; 'स्कोप्स' का वर्णन किया गया है।

कोई 'http:' लिंक नहीं; टीएलएस 1। 2+.

कैश/पहचान

Для GET - 'ETag/Last-Modified'; लिखने के लिए - 'Idempotency-Key' (जहाँ लागू होता है)।

प्रलेखन

'summmary', 'विवरण', अनुरोधों/प्रतिक्रियाओं (वैध) के उदाहरण।

11) स्वचालित जांच के उदाहरण

11. 1 अनिवार्य सुरक्षा हेडर का सत्यापन (वर्णक्रमीय)

yaml security-headers:
given: "$.paths[][].responses['200'].headers"
then:
function: truthy

11. 2 ओपनापी-डिफ़ (छद्म सीआई चरण)

openapi-diff --fail-on-incompatible base.yaml pr.yaml

11. 3 बफ ब्रेकिंग-चेक

buf breaking --against '.git#branch=main'

12) संविदाओं की गुणवत्ता की अवलोकन

मेट्रिक्स: पीआर का हिस्सा त्रुटियों को जोड़ ने, समय को ठीक करने, ब्रेकिंग प्रयासों की संख्या, नियमों के अनुसार "ऋण"।

डैशबोर्ड: एकीकृत त्रुटि योजना के लिए प्रवासन प्रगति, उदाहरण के साथ कवरेज, संस्करण स्थिरता।

13) एंटीपैटर्न

"डॉक्टर" कोड से अलग रहता है - desynchronization। अनुबंध को सेवा के करीब रखें और एक वर्तमान कलाकृति जारी करें।

लिंटर केवल हाथ से। एक कठिन पीआर-गेट की आवश्यकता है।

यादृच्छिक उदाहरण (गैर-नियतात्मक) - चेक में गुच्छे।

कोई नकारात्मक उदाहरण और त्रुटि कोड।

प्रत्येक सेवा के लिए त्रुटि योजना का पुनर्निवेश।

प्रोटोबुफ ब्रेकिंग चेक को नजरअंदाज करना (टैग बदलना "आंख से")।

14) आईगेमिंग/वित्त की विशिष्टताएं

मुद्रा क्षेत्र - स्थिर स्केल/राउंडिंग; फ्लोट निषेध।

अनिवार्य हेडर 'एक्स-टेनेंट', 'एक्स-रीजन' और 'ट्रेसपेरेंट' का पता लगाएं।

भुगतान राइट-हैंडल: 'आइडेम्पोटेंसी-की', 'रेट्री-आफ्टर' की जाँच और 409/201 शब्दार्थ सही।

वेबहूक PSP/KYC: HMAC/mTLS को ' योजनाओं' में वर्णित किया गया है; एंटी-रिप्ले ('एक्स-टाइमस्टैम्प', विंडो)।

क्षेत्रीय प्रतिबंध और त्रुटि स्थानीयकरण ('सामग्री-भाषा')।

15) प्रोड रेडीनेस चेकलिस्ट

• वर्णक्रमीय/Redocly प्रोफाइल पूर्व-प्रतिबद्ध और पीआर-गेट में डिजाइन और जुड़े हुए हैं।
• एकल त्रुटि पैटर्न और स्टेटस - प्रतिबद्ध और जाँच की गई।
• openapi-diff/GraphQL इंस्पेक्टर/buf - ब्लॉक ब्रेकिंग परिवर्तन।
• अनुरोधों/प्रतिक्रियाओं के उदाहरण मान्य हैं; pagination/फ़िल्टर प्रलेखित।
• योजनाएं और स्कोप भरे जाते हैं; कोई http लिंक नहीं है।
• प्रोटोबुफ़के लिए: हटाए गए टैग पर 'आरक्षित'; नए क्षेत्र - वैकल्पिक।
• सेमग्रेप/कोड लिंटर्स सक्षम; लॉग में रहस्य मास्किंग।
• सीआई अनुबंध कलाकृतियों और लिंटिंग रिपोर्टों को प्रकाशित करता है।
• प्लेबुक: ब्रेकिंग-डिफ़ा (रोलबैक, हॉटफ़िक्स, इंटीग्रेटर्स को सूचनाएँ) पर कैसे कार्य करें।

16) टीएल; डीआर

स्वचालित अनुबंध लिंटिंग (स्पेक्ट्रल/रेडोक्ली, बफ/ग्राफक्यूएल इंस्पेक्टर) और सिमेंटिक डिफ को लागू करें, एक त्रुटि/स्थिति/पगिनेशन/सुरक्षा योजना को ठीक करें, पीआर-गेट को कनेक्ट करें और कलाकृतियों के रूप में अनुबंध करें। कोई भी ब्रेकिंग डिफ एक ब्रेक लाइट है। पैसे/भुगतान के लिए - विशेष नियम (पहचान, 'रेट्री-आफ्टर', एचएमएसी/एमटीएलएस)।