API linting va statik tahlil

1) Nima uchun API lintlash kerak

• nomuvofiq va yashirin o’zgarishlarning oldini oladi;
• maqomlarni, xatolarni, paginatsiyani, xavfsizlikni birxillashtiradi;
• spetsifikatsiyalarni mashina-tekshiriladigan va relizlarni oldindan aytib bo’ladigan qiladi;
• ovozi va onbording vaqtini kamaytiradi.

Printsip: "kontraktlar avtomatik tarzda tekshiriladi; Yashil lintingsiz PR saqlanmaydi".

2) Linting obyektlari

1. Kontraktlar: OpenAPI/AsyncAPI/GraphQL SDL, Protobuf/Avro/JSON Schema.
2. Amalga oshirish: REST/gRPC ruchkalar, middleware, maqom kodlari/sarlavhalar.
3. Infratuzilma: xavfsizlik sarlavhalari, limitlar, kesh siyosati.
4. Qo’shimcha artefaktlar: misollar (examples), Postman-kolleksiyalar, xato sxemalari.

3) HTTP API uchun asosiy qoidalar (tavsiya etilgan profil)

3. 1 Nota va URL

snake_case JSON, kebab-case yoki bir xil kebab-case/’/v1/...’.
Resurslar - koʻplik: ’/v1/payments’, ichki - ’/v1/wallets/{ id }/transactions’.
path-params sifatida identifikatorlar: ’/v1/payments/{ payment _ id}’(turi: string, formati: uuid).

3. 2 Usullar va maqomlar

’GET’ - 200/206;’POST’- 201 (+’Location’), mojarolar - 409; validatsiya - 422; limitlar - 429 (+’Retry-After’).
Xato uchun 200 qaytarilmasin. Shartli so’rovlar - 304’If-None-Match’bo’yicha.

3. 3 Xatolar (yagona format)

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

Majburiy:’code’,’message’,’trace _ id’; lokal -’Content-Language’orqali.

3. 4 Paginatsiya/filtrlar

Cursor-based: `page_size`, `page_token`, ответ: `next_page_token`.
Filtrlar va saralash -’parameters’da hujjatlashtirilgan whitelists.

3. 5 Xavfsizlik

Yagona security sxemasi: OAuth2/OIDC scopes yoki mTLS; ’http’ (faqat’https’) ni taqiqlash.
Sezgir sarlavhalarni qaytarmaslik, namunalarda tokenlarni yashirish.

3. 6. Cheklovlar va o’lchamlar

Sarlavhalar/tana limitlari: 413/414/431; ruxsat etilgan maksimal qiymatlarni hujjatlashtiring.

4) Asboblar va ekotizim

4. 1 OpenAPI

Spectral (JSON/YAML lint), Redocly linter, oas-diff/openapi-diff (semantic diff), schemathesis/dredd (bajariladigan tekshiruvlar).

4. 2 Protobuf/gRPC

buf (lint + breaking check), protolint, SDK generatorlari; tahlil uchun gnostic.

4. 3 GraphQL

graphql-schema-linter, graphql-inspector (breaking).

4. 4 Kodli linterlar va SAST

ESLint, golangci-lint, Detekt/Ktlint, Pylint/Flake8, Semgrep (API-hidlar va security namunalari).

5) Qoidalar namunalari: Spectral/Redocly

5. 1 Spectral (misol’spectral. 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 (parcha’.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) Protobuf/gRPC: buf-profil

6. 1 `buf. yaml`

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

• Dala raqamlaridan qayta foydalanmaslik; olib tashlanadiganlar -’reserved’.
• Yangi maydonlar -’optional’yoki defoltli; turlarini/semantikasini o’zgartirmaslik.

7) Semantik diff va «buzuvchi» o’zgarishlar

7. 1 HTTP

• maydon turi/majburiyligini o’zgartirish;
• maqom/yo’nalish/parametrni olib tashlash;
• enum/diapazon torayishi;
• id (uuid → string) formatini oʻzgartirish.

• majburiy bo’lmagan maydonlarni qo’shish;
• happy-path ga ta’sir qilmaydigan yangi maqomlar (masalan, hujjatlashtirilgan’422’);
• enum kengayishi.

7. 2 gRPC/Protobuf

’reservedsiz’ maydonni olib tashlash/raqamni oʻzgartirish - breaking.
Turni oʻzgartirish (int32 → string) - breaking.
Yangi tagni optional sifatida qoʻshish - odatda safe.

8) Kontraktlar linting va kod aloqasi

1. Shartnoma → kod: SDK/server qulflarini yaratish, testlardagi salbiy misollar.

2. Kod → kontrakt: spetsifikatsion testlar, maqom/sarlavhalarni avtomatik tekshirish.

• taqiqlash’return 200’bilan’error! = nil’;
• to’lovlarning write-yo’nalishlarida majburiy «Idempotency-Key»;
• loglarda tokenlarni yashirish.

9) CI/CD paypline (referens)

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

• breaking-diff mavjud;
• bazaviy qoidalar buzilgan (maqomi/xavfsizligi/xatolari);
• parametrlarning namunalari/tavsiflari mavjud emas.

10) Qoidalar katalogi (tashkilotingiz uchun namunasi)

Identifikatorlar va turlar

`_id` — `string`, `format: uuid`.
Pul maydonlari -’string ’/’ decimal’s scale; valyuta - ISO-4217.

Xatolar

Yagona sxema (§ 3 ga qarang. 3), kodlari:’400/401/403/404/409/422/429/5xx’.
Har doim’trace _ id’;’Retry-After’uchun 429/503.

Paginatsiya

Faqat cursor; max’page _ size’hujjatlashtirilgan.

Xavfsizlik

Barcha operatsiyalar -’security’blok; ’scopes’ tasvirlangan.
Hech qanday’http:’havolalar; TLS 1. 2+.

Kesh/idempotentlik

Для GET — `ETag/Last-Modified`; write uchun -’Idempotency-Key’(qo’llanilishi mumkin bo’lgan joyda).

Hujjatlar

’summary’,’description’, soʻrov/javob namunalari (haqiqiy).

11) Avtomatlashtirilgan tekshirishlar namunalari

11. 1 Majburiy xavfsizlik sarlavhalarini tekshirish (Spectral)

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

11. 2 openapi-diff (psevdo CI-qadam)

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

11. 3 buf breaking-check

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

12) Kontraktlar sifatining kuzatilishi

Metriklar: linting xatolari bilan PR ulushi, fix vaqti, breaking-urinishlar soni, qoidalar bo’yicha «qarzlar».
Dashbordlar: yagona xato sxemasiga migratsiya taraqqiyoti, misollar bilan qoplash, versiyalarning barqarorligi.

13) Antipatternlar

«Doc» koddan alohida yashaydi → rassinxronizatsiya. Shartnomani xizmatning yonida saqlang va versiyalangan artefaktni chiqaring.
Linter faqat qoʻlda. Qattiq PR-gate kerak.
Tasodifiy misollar (non-deterministic) - tekshirishlarda fleykalar.
Salbiy misollar va xato kodlari yo’qligi.
Har bir servis uchun xato sxemasini qayta ishlab chiqish.
Protobuf breaking tekshiruvlarini eʼtiborsiz qoldirish.

14) iGaming/Moliya xususiyatlari

Pul maydonlari - belgilangan masshtab/yaxlitlash; float taqiqlanadi.
Majburiy sarlavhalar’X-Tenant’,’X-Region’va trastirovka’traceparent’.
To’lov write-ruchkalar:’Idempotency-Key’,’Retry-After’va to’g "ri 409/201 semantiklar mavjudligini tekshirish.
PSP/KYC: HMAC/mTLS vebxuklari’securitySchemes’da tasvirlangan; anti-replay (’X-Timestamp’, oyna).
Mintaqaviy cheklovlar va xatolarni mahalliylashtirish (’Content-Language’).

15) Prod-tayyorlik chek-varaqasi

• Spectral/Redocly profillari rasmiylashtirilgan va pre-commit va PR-gate ga ulangan.
• Xatolar va maqomlarning yagona sxemasi - qayd etildi va tekshirilmoqda.
• openapi-diff/GraphQL Inspector/buf - breaking-oʻzgarishlarni blokirovka qiladi.
• So’rovlar/javoblar namunalari validna; paginatsiya/filtrlar hujjatlashtirilgan.
• SecuritySchemes va scopes to’ldirilgan; Hech qanday http bogʻlamalari yoʻq.
• Protobuf uchun:’reserved’masofadagi taglarda; yangi maydonlar - optional.
• Semgrep/kod linterlari kiritilgan; sahifalarda sirlarni yashirish.
• CI shartnomalar artefaktlari va linting hisobotlarini nashr etadi.
• Pleybuk: breaking-diffda (rollback, hotfix, integratorlarga bildirishnomalar) qanday harakat qilish kerak.

16) TL; DR

Kontraktlarning avtomatik lintingini (Spectral/Redocly, buf/GraphQL Inspector) va semantik diffni joriy qiling, xatolar/maqomlar/paginatsiya/xavfsizlikning yagona sxemasini qayd eting, PR-gate-ga ulaning va kontraktlarni artefakt sifatida nashr eting. Har qanday breaking-diff - to’xtash signali. Pul/to’lovlar uchun - alohida qoidalar (idempotentlik,’Retry-After’, HMAC/mTLS).