API linting və statik analiz

1) Niyə API Lint

• uyğunsuz və gizli dəyişikliklərin qarşısını alır;
• statusları, səhvləri, pozuntuları, təhlükəsizliyi birləşdirir;
• spesifikasiyaları maşın tərəfindən yoxlanıla bilən və buraxılışları proqnozlaşdırıla bilən edir;
• revyu dəyəri və onbording vaxt azaldır.

Prinsip: "müqavilələr avtomatik yoxlanılır; yaşıl linting olmadan PR saxlamaq deyil".

2) Lintinq obyektləri

1. Müqavilələr: OpenAPI/AsyncAPI/GraphQL SDL, Protobuf/Avro/JSON Schema.
2. Realizasiya: REST/gRPC qələmləri, orta ölçülü, status kodları/başlıqlar.
3. Infrastruktur: təhlükəsizlik başlıqları, limitlər, cache siyasəti.
4. Əlaqəli artefaktlar: nümunələr (examples), Postman kolleksiyaları, səhv sxemləri.

3) HTTP API üçün əsas qaydalar (tövsiyə olunan profil)

3. 1 Notasiya və URL

snake_case JSON, kebab-case və ya vahid kebab-case/'/v1/... '.
Resurslar - çoxluq: '/v1/payments ', daxili - '/v1/wallets/{ id }/transactions'.
path-params kimi identifikatorlar: '/v1/payments/{ payment _ id} '(növü: string, formatı: uuid).

3. 2 Metodlar və statuslar

'GET' - 200/206; 'POST' - 201 (+ 'Location'), münaqişələr - 409; validasiya - 422; limitlər - 429 (+ 'Retry-After').
Xətalar üçün 200 qaytarmayın. Şərti sorğular - 304 'If-None-Match'.

3. 3 Səhvlər (vahid format)

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

Məcburi: 'code', 'message', 'trace _ id'; lokal - 'Content-Language' vasitəsilə.

3. 4 Paginasiya/filtrlər

Cursor-based: `page_size`, `page_token`, ответ: `next_page_token`.
Filtrlər və çeşidləmə - 'parameters' sənədləşdirilmiş whitelists.

3. 5 Təhlükəsizlik

Vahid təhlükəsizlik sxemi: OAuth2/OIDC scopes və ya mTLS; 'http' (yalnız 'https') qadağan edin.
Həssas başlıqları geri qaytarmayın, nümunələrdə tokenləri maskalamayın.

3. 6 Məhdudiyyətlər və ölçülər

Başlıq/bədən limitləri: 413/414/431; icazə verilən maksimum qiymətləri sənədləşdirin.

4) Alətlər və ekosistem

4. 1 OpenAPI

Spectral (JSON/YAML lint), Redocly linter, oas-diff/openapi-diff (semantic diff), schemathesis/dredd (yerinə yetirilən yoxlamalar).

4. 2 Protobuf/gRPC

buf (lint + breaking check), protolint, SDK generatorları; analiz üçün gnostic.

4. 3 GraphQL

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

4. 4 Kod linterləri və SAST

ESLint, golangci-lint, Detekt/Ktlint, Pylint/Flake8, Semgrep (API qoxu və təhlükəsizlik şablonları).

5) Qaydaların nümunələri: Spectral/Redocly

5. 1 Spectral (nümunə '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 (fraqment '.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 profili

6. 1 `buf. yaml`

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

• Sahə nömrələrini yenidən istifadə etməyin; silinən - 'reserved'.
• Yeni sahələr - 'optional' və ya defolt ilə; növləri/semantika dəyişdirmək deyil.

7) Semantik diff və «qırıcı» dəyişikliklər

7. 1 HTTP

• sahənin növünün/məcburiyyətinin dəyişdirilməsi;
• status/marşrut/parametrin silinməsi;
• enum/diapazonun daralması;
• id formatının dəyişdirilməsi (uuid → string).

• isteğe bağlı sahələrin əlavə edilməsi;
• happy-path-a təsir etməyən yeni statuslar (məsələn, sənədləşdirilmiş '422');
• enum genişləndirilməsi.

7. 2 gRPC/Protobuf

'reserved' olmadan sahənin silinməsi/nömrənin dəyişdirilməsi - breaking.
Növün dəyişdirilməsi (int32 → string) - breaking.
optional kimi yeni bir etiket əlavə - adətən safe.

8) Linting müqavilələr və kod rabitə

1. Müqavilə → kod: SDK/server qapaqlarının yaradılması, testlərdə mənfi nümunələr.

2. Kod → müqavilə: spesifikasiya testləri, status/başlıqların avtomatik yoxlanılması.

• qadağa 'return 200' ilə 'error! = nil';
• write-ödəniş marşrutlarında məcburi «Idempotency-Key»;
• loqlarda tokenlərin maskalanması.

9) CI/CD paypline (istinad)

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 var;
• əsas qaydalar pozulur (statuslar/təhlükəsizlik/səhvlər);
• parametrlərin nümunələri/təsviri yoxdur.

10) Qaydalar kataloqu (təşkilatınız üçün şablon)

Identifikatorlar və növlər

`_id` — `string`, `format: uuid`.
Pul sahələri - scale ilə 'string '/' decimal'; valyuta - ISO-4217.

Səhvlər

Vahid sxem (bax § 3. 3), kodları: '400/401/403/404/409/422/429/5xx'.
Həmişə 'trace _ id'; 'Retry-After' üçün 429/503.

Paqinasiya

Yalnız cursor; max 'page _ size' sənədləşdirilmişdir.

Təhlükəsizlik

Bütün əməliyyatlar - 'security' blok; təsvir 'scopes'.
No 'http:' link; TLS 1. 2+.

Cache/idempotentlik

Для GET — `ETag/Last-Modified`; write üçün - 'Idempotency-Key' (harada tətbiq olunur).

Sənədləşmə

'summary', 'description', sorğu/cavab nümunələri (valid).

11) Avtomatlaşdırılmış yoxlama nümunələri

11. 1 Məcburi təhlükəsizlik başlıqlarının yoxlanılması (Spectral)

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

11. 2 openapi-diff (psevdo CI-addım)

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

11. 3 buf breaking-check

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

12) Müqavilələrin keyfiyyətinin müşahidə edilməsi

Metriklər: lintinq səhvləri ilə PR payı, fiks vaxtı, fasilə cəhdlərinin sayı, qaydalara görə «borclar».
Daşbordlar: vahid səhv sxeminə miqrasiyanın irəliləməsi, nümunələrlə əhatə olunması, versiyaların sabitliyi.

13) Antipattern

«Doc» koddan ayrı yaşayır → rassinxronizasiya. Müqaviləni xidmətin yanında saxlayın və versiyalı artefakt buraxın.
Linter yalnız əl ilə. Sərt PR-gate lazımdır.
Təsadüfi nümunələr (qeyri-deterministik) - yoxlamalarda fleykalar.
Mənfi nümunələrin və səhv kodlarının olmaması.
Hər xidmət üçün səhv sxeminin yenidən hazırlanması.
Protobuf breaking yoxlamalarına məhəl qoymamaq («göz» etiketlərini dəyişdirmək).

14) iGaming/Maliyyə Xüsusiyyətləri

Pul sahələri - sabit miqyaslı/dairəvi; float qadağası.
Məcburi başlıqlar 'X-Tenant', 'X-Region' və 'traceparent' izləri.
Ödəniş qələmləri: 'Idempotency-Key', 'Retry-After' və düzgün 409/201 semantiklərin mövcudluğunu yoxlayın.
PSP/KYC vebhukları: HMAC/mTLS 'securitySchemes' -də təsvir edilmişdir; anti-replay ('X-Timestamp', pəncərə).
Regional məhdudiyyətlər və səhvlərin lokallaşdırılması ('Content-Language').

15) Prod hazırlıq yoxlama siyahısı

• Spectral/Redocly profilləri rəsmiləşdirilmiş və pre-commit və PR-gate qoşulmuşdur.
• Vahid xəta sxemi və statuslar - qeydə və yoxlanılır.
• openapi-diff/GraphQL Inspector/buf - blok breaking-dəyişikliklər.
• Sorğu/cavab nümunələri validna; pagination/filters sənədləşdirilmişdir.
• SecuritySchemes və scopes dolu; http bağlantıları yoxdur.
• Protobuf üçün: uzaqdan etiketlərdə 'reserved'; yeni sahələr - optional.
• Semgrep/kod linterləri daxildir; lojalarda sirləri gizlətmək.
• CI müqavilələrin artefaktlarını və lintinq hesabatlarını dərc edir.
• Playbook: breaking-diff (rollback, hotfix, inteqratorlara bildirişlər) ilə necə davranmaq olar.

16) TL; DR

Müqavilələrin avtomatik lintinqini (Spectral/Redocly, buf/GraphQL Inspector) və semantik diff tətbiq edin, vahid səhv/status/pagination/təhlükəsizlik sxemini qeyd edin, PR qapısını bağlayın və müqavilələrin artefakt kimi yayımlanmasını təmin edin. Hər hansı bir fasilə - dayandırma siqnalı. Pul/ödənişlər üçün - xüsusi qaydalar (idempotentlik, 'Retry-After', HMAC/mTLS).