captuseala API si analiza statica

1) De ce link-ul API

• Prevenirea schimbărilor incompatibile și implicite
• unifica statusurile, erorile, paginatia, securitatea;
• face specificațiile verificabile de mașină și eliberează previzibile;
• reduce costul de revizuire și timpul de îmbarcare.

Principiul: "contractele sunt verificate automat; PR fără linii verzi nu deține"

2) Facilități de linting

1. Contracte: OpenAPI/AsyncAPI/GraphQL SDL, Protobuf/Avro/JSON Schema.
2. Implementare: stilouri REST/gRPC, middleware, coduri de stare/antete.
3. Infrastructură: anteturi de securitate, limite, politici cache.
4. Artefacte conexe: exemple, colecții Postman, scheme de eroare.

3) Reguli de bază pentru API HTTP (profil recomandat)

3. 1 Notație și URL

snake_case în corpurile JSON, kebab-caz în căi, sau kebab-caz uniform/"/v1/... '.
Resurse - plural: '/v1/payments', imbricate - '/v1/wallets/{ id }/transactions '.
Identificatori ca parametri de cale: '/v1/payments/{ payment _ id} '(tip: string, format: uuid).

3. 2 Metode și stări

"GET" - 200/206; " POST "- 201 (+" Locație "), conflicte - 409; validare - 422; limite - 429 (+ 'Retry-After').
Nu returnați 200 pentru erori. Interogări condiționate - 304 prin 'If-None-Match'.

3. 3 Erori (format unic)

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

Necesar: 'cod', 'mesaj', 'trace _ id'; locale - prin „Content-Language”.

3. 4 Paginare/filtre

Cursor-based: 'page _ size', 'page _ token', ответ: 'next _ page _ token'.
Filtre și sortare - liste albe documentate în „parametri”.

3. 5 Siguranţă

Sistem de securitate uniform: scopuri OAuth2/OIDC sau mTLS; neagă „http” (numai „https”).
Nu returnați anteturile sensibile, mascați jetoanele în exemple.

3. 6 Limitări și dimensiuni

Titlul/limitele corpului: 413/414/431; Documentați valorile maxime permise.

4) Instrumente și ecosistem

4. 1 OpenAPI

Spectral (JSON/YAML scame), Redocly linter, oas-diff/openapi-diff (diff semantic), schemathesis/dredd (verificări în curs).

4. 2 Protobuf/gRPC

buf (scame + verificare de rupere), protolint, generatoare SDK; gnostic pentru analiză.

4. 3 GraphQL

grafql-schema-linter, graphql-inspector (rupere).

4. 4 Code Linters și SAST

ESLint, golangci-scame, Detekt/Ktlint, Pylint/Flake8, Semgrep (miros API și șabloane de securitate).

5) Exemple de reguli: Spectral/Redocly

5. 1 Spectral (exemplu "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 (fragment ".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: profil buf

6. 1 'buf. yaml'

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

• Nu reutilizați numerele de câmp; eliminat - în „rezervat”.
• Câmpuri noi - „opționale” sau cu valori implicite; nu schimba tipurile/semantica.

7) Diff semantic și „rupere” modificări

7. 1 HTTP

• Modificarea tipului de câmp/obligatorie
• Șterge starea/traseul/parametrul
• enum/gama de îngustare;
• schimbarea formatului id (uuid → string).

• Adăugarea câmpurilor opţionale
• Noi stări care nu afectează calea fericită (de exemplu, documentat „422”)
• extensie enum.

7. 2 gRPC/Protobuf

Ștergerea unui câmp fără „rezervă ”/renumbering - breaking.
Schimbare de tip (șir de → int32) - rupere.
Adăugarea unui nou tag ca opțional este de obicei sigură.

8) Contract și Code Linking

1. Codul → contractului: generarea de cotoare SDK/server, exemple negative în teste.

2. Codul → contractului: teste de specificații, verificarea automată a stărilor/anteturilor.

• disallowing 'return 200' when 'error! = nil';
• obligatoriu „Idempotency-Key” pe rute de plată scrise;
• mascarea tokenuri în jurnalele.

9) CI/CD conductă (de referință)

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

• există breaking-diff;
• Regulile de bază au fost încălcate (stări/securitate/erori)
• nu există exemple/descrieri ale parametrilor.

10) Catalog de reguli (model pentru organizația dvs)

Identificatori și tipuri

'_ id' -' string ',' format: uuid '.
Câmpuri monetare - „string ”/„ zecimal” cu scară; valută - ISO-4217.

Greșeli

Schema unificată (a se vedea § 3. 3), coduri: '400/401/403/404/409/422/429/5xx'.
Întotdeauna „trace _ id';” Retry-After 'pentru 429/503.

Paginare

Numai cursorul; max 'page _ size' este documentat.

Siguranță

Toate operațiunile - bloc de „securitate”; „scopuri” sunt descrise.
Nu există legături „http:”; TLS 1. 2+.

Memorie cache/idempotenta

Для GET - 'ETag/Last-Modified'; pentru a scrie - „Idempotency-Key” (dacă este cazul).

Documentație

„sumar”, „descriere”, exemple de cereri/răspunsuri (valabile).

11) Exemple de verificări automate

11. 1 Verificarea anteturilor de securitate obligatorii (Spectral)

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

11. 2 openapi-diff (pasul IÎ pseudo)

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

11. 3 buf breaking-check

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

12) Observabilitatea calității contractelor

Valori: cota de PR-uri cu erori de legare, timp fix, numărul de încercări de rupere, „datorii” în conformitate cu regulile.
Tablouri de bord: progresul migrației la schema de eroare unificată, acoperirea cu exemple, stabilitatea versiunii.

13) Antipattern

„Doc” trăiește separat de codul → desincronizare. Păstrați contractul aproape de serviciu și eliberați un artefact versionat.
Linter doar cu mâna. Am nevoie de o poartă de PR tare.
Exemple aleatorii (non-deterministe) - fulgi în verificări.
Nu există exemple negative și coduri de eroare.
Reinventarea schemei de eroare pentru fiecare serviciu.
Ignorarea verificărilor de rupere Protobuf (schimbarea etichetelor „cu ochi”).

14) Specificul iGaming/Finanțe

Câmpuri valutare - scară fixă/rotunjire; interzicerea plutirii.
Anteturile obligatorii „X-Tenant”, „Regiunea X” și urme „traceparent”.
Plata scrie-mânere: verificarea pentru „Idempotency-Key”, „Retry-After” și corecta 409/201 semantica.
Webhooks PSP/KYC: HMAC/mTLS sunt descrise în „securitySchemes”; anti-reluare ('X-Timestamp', fereastră).
Restricții regionale și localizarea erorilor ('Content-Language').

15) Lista de verificare Prod Readiness

• Profilele Spectral/Redocly sunt proiectate și conectate în pre-comite și PR-gate.
• Un singur model de eroare și statusuri - angajat și verificat.
• openapi-diff/GraphQL Inspector/buf - bloc modificări de rupere.
• Exemple de cereri/răspunsuri sunt valide; paginare/filtre documentate.
• SecuritySchemes și scopuri sunt umplute; Nu există link-uri http.
• Pentru Protobuf: „rezervat” pe etichetele șterse; câmpuri noi - opțional.
• Semgrep/cod linters activat; mascarea secretelor în buşteni.

CI publică artefacte contractuale și rapoarte de linting.

• Playbook: cum să acționeze atunci când breaking-diffa (rollback, hotfix, notificări către integratori).

16) TL; DR

Implementați linii automate de contract (Spectral/Redocly, buf/GraphQL Inspector) și diff semantic, remediați o singură eroare/stare/paginare/securitate, conectați PR-gate și publicați contracte ca artefacte. Orice diff de rupere este o lumină de frână. Pentru bani/plăți - reguli speciale (idempotență, „Retry-After”, HMAC/mTLS).