API linting we statiki analiz

1) Näme üçin API çekmeli?

• gabat gelmeýän we düşnüksiz üýtgeşmeleriň öňüni alýar;
• statuslary, ýalňyşlyklary, paginasiýany, howpsuzlygy birleşdirmek;
• spesifikasiýalary maşyn-barlanylýan we goýberilişleri öňünden aýdyp boljak edýär;
• rebu we onbording wagtynyň bahasyny gysgaldýarlar.

Prinsipi: "şertnamalar awtomatiki usulda barlanýar; PR ýaşyl linting bolmasa saklanmaz".

2) Linting obýektleri

1. Şertnamalar: OpenAPI/AsyncAPI/GraphQL SDL, Protobuf/Euro/JSON Shema.
2. Ýerine ýetiriş: REST/gRPC ruçkalary, middleware, status kodlary/sözbaşylar.
3. Infrastruktura: howpsuzlyk sözbaşylary, çäklendirmeler, kesiş syýasaty.
4. Degişli artefaktlar: mysallar (examples), Postman-kolleksiýalar, ýalňyşlyk shemalary.

3) HTTP API üçin esasy düzgünler (maslahat berilýän profil)

3. 1 Bellik we URL

JSON jisimlerinde snake_case, ýollarda kebab-case ýa-da birmeňzeş kebab-case/'/v1/... '.
Resurslar - köplük: '/v1/payments ', içerki - '/v1/wallets/{ id }/transactions'.
Path-params ýaly kesgitleýjiler: '/v1/payments/{ payment _ id} '(görnüşi: string, formaty: uuid).

3. 2 Usullar we statuslar

'GET' - 200/206; 'POST' - 201 (+ 'Location'), gapma-garşylyklar - 409; tassyklama - 422; çäkleri - 429 (+ 'Retry-After').
Hatalar üçin 200 gaýtaryp bermäň. Şertli haýyşlar - 304 'If-None-Match'.

3. 3 Ýalňyşlyklar (ýekeje format)

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

Hökmany: 'code', 'message', 'trace _ id'; lokal - 'Content-Language' arkaly.

3. 4 Paginasiýa/süzgüçler

Cursor-based: `page_size`, `page_token`, ответ: `next_page_token`.
Süzgüçler we sortlar - 'parameters' -de resminamalaşdyrylan whitelists.

3. 5 Howpsuzlyk

Birmeňzeş howpsuzlyk shemasy: OAuth2/OIDC skopes ýa-da mTLS; 'http' -ni gadagan etmek (diňe 'https').
Duýgur sözbaşylary yzyna gaýtarmaň, bellikleri mysallarda gizläň.

3. 6 Çäklendirmeler we ölçegler

Sözbaşylaryň/jisimleriň çäkleri: 413/414/431; iň ýokary rugsat edilýän bahalary resminamalaşdyryň.

4) Gurallar we ekosistema

4. 1 OpenAPI

Spectral (JSON/YAML lint), Redocly linter, oas-diff/openapi-diff (semantic diff), schemathesis/dredd (ýerine ýetirilýän barlaglar).

4. 2 Protobuf/gRPC

buf (lint + breaking check), protolint, SDK generatorlary; analiz üçin gnostic.

4. 3 GraphQL

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

4. 4 Kod linterleri we SAST

ESLint, golangci-lint, Detekt/Ktlint, Pylint/Flake8, Semgrep (API-ys we howpsuzlyk şablonlary).

5) Düzgünleriň mysallary: Spectral/Redocly

5. 1 Spectral (mysal '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 (bölek '.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: []

• Meýdan belgilerini gaýtadan ulanmazlyk; "reserved" -de aýrylýar.
• Täze meýdanlar - 'optional' ýa-da defoltly; Görnüşini/semantikasyny üýtgetmäň.

7) Semantiki diff we "döwýän" üýtgeşmeler

7. 1 HTTP

• meýdanyň görnüşiniň/borçlylygynyň üýtgemegi;
• statusy/ugry/parametrini aýyrmak;
• enum/diapazonyň daralmagy;
• id (uuid → string) formatyny üýtgetmek.

• goşmaça meýdanlary goşmak;
• happy-path-a täsir etmeýän täze statuslar (mysal üçin, resminamalaşdyrylan '422');
• giňeltmek enum.

7. 2 gRPC/Protobuf

'Reserved' -siz meýdançany aýyrmak/belgini üýtgetmek - breaking.
Görnüşini üýtgetmek (int32 → string) - breaking.
Täze belgi optional - adatça safe.

8) Şertnamalaryň lintinginiň we koduň baglanyşygy

1. Şertnama → kod: SDK/serwer düwmeleriniň öndürilmegi, synaglarda negatiw mysallar.

2. Kod → Şertnama: spesifikasiýa synaglary, statuslary/sözbaşylary awtomatiki barlamak.

• gadaganlyk 'return 200' -de 'error! = nil';
• tölegleriň write-ugurlarynda hökmany 'idempotency-Key';
• bloglarda bellikleri gizlemek.

9) CI/CD paypline (salgylanma)

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 bar;
• esasy düzgünler bozulsa (statuslar/howpsuzlyk/ýalňyşlyklar);
• parametrleriň mysallary/düşündirişleri ýok.

10) Düzgünler katalogy (guramaňyz üçin şablon)

Kesgitleýjiler we görnüşler

`_id` — `string`, `format: uuid`.
Pul meýdançalary - 'string '/' decimal' s scale; walýuta - ISO-4217.

Ýalňyşlyklar

Bitewi shema (§ 3 serediň. 3), kodlar: '400/401/403/404/409/422/429/5xx'.
Elmydama 'trace _ id'; 'Retry-After' üçin 429/503.

Paginasiýa

Diňe cursor; max 'page _ size' resminamalaşdyryldy.

Howpsuzlyk

Ähli amallar - 'security' blok; 'scopes' beýan edildi.
Baglanyşyklar ýok 'http:'; TLS 1. 2+.

Nagt/idempotentlik

Для GET — `ETag/Last-Modified`; write üçin - 'Idempotency-Key' (bar ýerinde).

Dokumentasiýa

'summary', 'description', soraglaryň/jogaplaryň mysallary (dogry).

11) Awtomatlaşdyrylan barlaglaryň mysallary

11. 1 Hökmany howpsuzlyk sözbaşylaryny barlamak (Spectral)

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

11. 2 openapi-diff (psevdo CI ädim)

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

11. 3 buf breaking-check

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

12) Şertnamalaryň hiline syn etmek

Metrikler: linting ýalňyşlyklary bolan PR paýy, fiks wagty, breaking-synanyşyklaryň sany, düzgünler boýunça "bergiler".
Daşbordlar: göçmegiň bitewi ýalňyşlyk shemasyna ösüşi, mysallar bilen örtülmegi, wersiýalaryň durnuklylygy.

13) Antipatternler

"Doc" koddan aýry ýaşaýar → rasinhronizasiýa. Şertnamany hyzmatyň ýanynda saklaň we wersiýaly artefakt bilen çykaryň.
Linter diňe el bilen. Gaty PR-gate gerek.
Tötänleýin mysallar (deterministik däl) - barlaglarda fleýkalar.
Negatiw mysallaryň we ýalňyşlyk kodlarynyň ýoklugy.
Her hyzmat üçin ýalňyşlyklaryň shemasyny täzeden edinmek.
Protobuf breaking-barlaglaryny äsgermezlik etmek (bellikleri "göz bilen" üýtgetmek).

14) iGaming/Maliýe aýratynlyklary

Pul meýdanlary - kesgitlenen masştab/tegelek; float gadaganlygy.
Hökmany sözbaşylar 'X-Tenant', 'X-Region' we 'traceparent'.
Töleg write-ruçkalary: 'Idempotency-Key', 'Retry-After' we dogry 409/201 semantikleriň barlygyny barlamak.
PSP/KYC: HMAC/mTLS webhuklary 'securitySchemes' -de beýan edilýär; anti-replay ('X-Timestamp', penjire).
Sebitleýin çäklendirmeler we ýalňyşlyklaryň lokalizasiýasy ('Content-Language').

15) Prod-taýynlyk çek-sanawy

• Spectral/Redocly profilleri düzüldi we pre-commit we PR-gate birikdirildi.
• Ýeke-täk ýalňyşlyklar we statuslar shemasy - hasaba alyndy we barlanýar.
• openapi-diff/GraphQL Inspector/buf - breaking-üýtgeşmeleri bloklaýar.
• Soraglaryň/jogaplaryň mysallary tassyklanýar; paginasiýa/süzgüçler dokumentleşdirildi.
• SecuritySchemes we scopes dolduryldy; http baglanyşyklary ýok.
• Protobuf üçin: 'reserved' uzakdaky belliklerde; Täze meýdanlar - optional.
• Semgrep/kod linterleri goşuldy; syr gizlemek.
• CI şertnamalaryň artefaktlaryny we linting hasabatlaryny çap edýär.
• Pleybuk: breaking-diff (rollback, hotfix, integratorlara bildirişler) bilen nähili hereket etmeli?

16) TL; DR

Şertnamalaryň awtomatiki lintingini (Spectral/Redocly, buf/GraphQL Inspector) we semantik diff giriziň, ýeke-täk ýalňyşlyk/status/paginasiýa/howpsuzlyk shemasyny düzüň, PR-gate birikdiriň we şertnamalary artefakt hökmünde çap ediň. Islendik arakesme-diff - durma signaly. Pul/tölegler üçin - aýratyn düzgünler (idempotentlik, 'Retry-After', HMAC/mTLS).