Sviluppo REST e OpenAPI per API Ben Documentate e Manutenibili

OpenAPI 2 (Swagger) utilizza un oggetto definitions separato e ha supporto limitato per le funzionalità moderne di JSON Schema. OpenAPI 3.0 ha introdotto components, requestBody e tipi di media per le risposte multiple. OpenAPI 3.1 è completamente allineato con JSON Schema Draft 2020-12, supportando nullable (null nell'array type), if/then/else, const e deprecated negli schema. Utilizziamo OpenAPI 3.1 per tutti i nuovi progetti e migriamo le spec più datate alla 3.1 durante le revisioni delle API.

Utilizziamo il versionamento tramite prefisso URL (/v1/, /v2/) come strategia principale — è esplicito, cacheable e visibile nei log e negli API gateway. Il versionamento via header (Accept: application/vnd.api.v2+json) si adotta quando la stabilità dell'URL è importante (integrazioni con partner). Manteniamo la versione precedente per un periodo di deprecazione documentato (tipicamente 6-12 mesi), aggiungiamo header Sunset e Deprecation agli endpoint deprecati e generiamo un changelog dalle diff delle spec OpenAPI.

Strumenti specifici per linguaggio generano OpenAPI dalle annotazioni del codice: Springdoc OpenAPI per Spring Boot (Java), la generazione di schema integrata in FastAPI (Python), tsoa o ts-rest per TypeScript, oapi-codegen per Go. Eseguiamo il linting OpenAPI con Spectral in CI per garantire convenzioni di naming, descrizioni obbligatorie, valori di esempio e completezza degli schemi di sicurezza. La spec generata viene committata nel repository e pubblicata su un developer portal ad ogni release.

Il contract testing verifica che l'implementazione del server corrisponda al contratto definito nella spec OpenAPI. Utilizziamo Prism (Stoplight) come mock server — i team consumer scrivono test contro Prism e il server reale durante lo sviluppo. Dredd o Schemathesis esegue la spec OpenAPI come suite di test sul server live in CI, testando ogni endpoint, metodo e codice di risposta definito nella spec. Un gate CI impedisce il merge se l'implementazione diverge dalla spec.

OAuth2 con PKCE per le API rivolte agli utenti; client credentials flow per la comunicazione service-to-service; validazione JWT al layer dell'API gateway (Kong, AWS API Gateway) con autorizzazione degli endpoint basata su scope. Rate limiting per client_id e per IP tramite contatore Redis. Validazione dell'input al layer dello schema (validazione JSON Schema prima che il handler venga eseguito). CORS limitato alle origini conosciute. Messaggi di errore dettagliati soppressi (nessuno stack trace, nessun dettaglio di servizi interni). Revisione OWASP API Security Top 10 prima di ogni lancio esterno.

Un reverse proxy (Nginx, HAProxy) instrada le richieste HTTP, termina TLS e bilancia il carico — non ha conoscenza specifica delle API. Un API gateway (Kong, AWS API Gateway, Azure APIM) aggiunge middleware specifico per le API: plugin di auth (validazione JWT/OAuth2), rate limiting per consumer, trasformazione di richiesta/risposta, logging per endpoint, developer portal e routing del versionamento delle API. Utilizziamo Nginx come reverse proxy sull'edge e Kong o AWS API Gateway come layer di API gateway per le problematiche specifiche delle API.

L'OWASP API Security Top 10 è la checklist standard del settore per le vulnerabilità delle API: 1) Broken Object Level Authorisation (BOLA - accesso agli oggetti di altri utenti); 2) Broken Auth; 3) Broken Object Property Level Authorisation (mass assignment); 4) Unrestricted Resource Consumption (rate limiting assente); 5) Broken Function Level Authorisation (endpoint admin accessibili agli utenti); 6) Unrestricted Access to Sensitive Business Flows; 7) Server-Side Request Forgery (SSRF); 8) Security Misconfiguration; 9) Improper Inventory Management (shadow API); 10) Unsafe Consumption of APIs. Testiamo ogni nuova API contro tutti i 10 punti prima del lancio esterno.