Cos’è l’API Linting e come lo usiamo per migliorare qualità e sicurezza

In un approfondimento dedicato alle linee guida API abbiamo spiegato quanto siano fondamentali, nel contesto di un API management moderno, concetti come quello delle API guidelines e di APIOps, quest’ultimo inteso come l’applicazione delle pratiche DevOps all’intero ciclo di vita delle API.
Se la progettazione delle API deve tener conto di specifiche linee guida definite dall’azienda e volte a standardizzare tematiche funzionali e di security, diventa necessaria un’attività (o uno strumento, a seconda della prospettiva di osservazione) di verifica della corretta progettazione di un’API fin dalla fase in cui questa viene pensata, descritta e formalizzata, ad esempio tramite la specifica OpenAPI. Questa attività prende il nome di API Linting.

L’API Linting e il suo ruolo nel ciclo di vita delle API

L’API Linting è un’attività assimilabile all’analisi statica del codice delle API e finalizzata a identificare eventuali incongruenze, anomalie, errori o violazioni di specifiche regole e standard definite nell’API style book aziendale.

L’API Linting permette quindi di evidenziare alcuni problemi di progettazione delle API come, ad esempio:

• Parametri mancanti o mal definiti;
• Nomi di endpoint ambigui o non standardizzati;
• Mancato rispetto delle convenzioni HTTP o REST;
• Mancato rispetto di convenzioni aziendali rispetto a linee guida di versioning;
• Problemi di formattazione nei payload (come JSON non valido);
• Mancanza di documentazione: il linting aiuta infatti a garantire che l’API sia sempre ben documentata e corredata di esempi.

Posizionare l’API Linting all’inizio del ciclo di vita delle API, cosa che Intesys fa da tempo e supporta i clienti nel fare altrettanto, garantisce che le API siano ben progettate, implementate in modo coerente, utilizzabili in modo uniforme e indipendente dai team che le hanno realizzate. Questo le rende più facili da usare, ma anche più sicure.

API Security: come la potenziamo con il linting

Come anticipato, un altro tema molto attuale e di interesse per Intesys è l’API Security. Anche in quest’ambito l’API Linting, abbinato all’approccio API First, ha una rilevanza centrale e diventa così una buona pratica sia per aspetti funzionali che di API security, integrandosi perfettamente nell’approccio di security by design che adottiamo in ogni nostro progetto.

Il concetto alla base del Linting ovviamente non cambia, ma le informazioni che veicola possono essere determinanti ai fini della progettazione sicura dell’API. Per esempio, il Linting può:

Per questa attività, in Intesys ci affidiamo a dei tool dedicati.
Tra questi, segnaliamo i software open source Spectral e Spectral CLI, che possono essere integrati nelle pipeline di CI/CD. Spectral consente di sfruttare dei RuleSet, ovvero delle librerie sia custom (della specifica azienda) che open source, ovvero – in quest’ultimo caso – degli insiemi di librerie già pubblicati dalle organizzazioni che sposano la filosofia open source.

Il linting, in sostanza, ci consente di ottenere il meglio dei due mondi: delle API coerenti in tutta l’organizzazione, facili da utilizzare da parte dei consumer, ben progettate, implementate e gestite, oltre che rispettose delle migliori pratiche di sicurezza.