Cos'è la progettazione API?

La progettazione dell'API è il processo di definizione e documentazione delle interazioni tra i componenti software. Ciò implica la definizione di diversi endpoint, la specificazione di tutti i formati da utilizzare e la definizione del comportamento di qualsiasi software che fa parte dell'API. In particolare, un'API progettata ha un significato speciale per il modo in cui i sistemi interagiscono tra loro e quale tipo di interazione si rivela efficace. 

È superficiale concludere che la scelta dell'API facilita la comunicazione multipartita e la sua chiarezza ed efficacia possono determinare la complessità del software. Spesso le persone non si rendono conto che la progettazione di un'API comporta diverse ripetizioni, soprattutto in situazioni in cui vengono trattati dati sensibili. Ciò richiede molti test per garantire che il sistema sia sia resistente che protetto.

Le API sono quindi classificate in base all'accessibilità, alla struttura e ai protocolli utilizzati. Ecco una ripartizione di questi tipi di API e delle loro caratteristiche: 

• Disponibilità: Le API possono essere pubbliche (in questo caso, queste API sono disponibili per chiunque) o private (sono rese disponibili a un numero limitato di utenti o organizzazioni).
• Architettura: Le API possono effettivamente essere RESTful e spesso utilizzano HTTP, così come SOAP, che è un protocollo XML più vecchio.   
• Protocolli: Le API possono anche essere categorizzate in base al protocollo sottostante, con le API Web su Internet e la nuova GraphQL ottimizzata per le query di dati, tra le altre.

Durante la progettazione delle API, l'aderenza a determinati standard e best practice, come i principi di progettazione RESTful, la selezione del metodo HTTP appropriato, il controllo delle versioni delle API e la memorizzazione nella cache dei dati. Queste misure possono influenzare aspetti quali l'accesso, l'affidabilità e l'estendibilità delle API, possibilmente con l'obiettivo di ottenere una migliore usabilità. 

Quando i verbi HTTP vengono utilizzati correttamente e accuratamente, diventa più efficiente descrivere l'operazione che dovrebbe essere completata sulla particolare risorsa. Il controllo delle versioni è importante per mantenere la compatibilità con le integrazioni esistenti durante l'apporto di modifiche.

Scegliere lo strumento giusto da utilizzare per creare la tua API è uno degli aspetti più cruciali se desideri un processo di sviluppo senza interruzioni. Comprendere le capacità e le limitazioni di piattaforme popolari come Stoplight, SwaggerHub e Apigee facilita il processo decisionale consapevole per scegliere l'opzione migliore. 

• Stoplight: L'editor visivo di Stoplight è progettato per facilitare la creazione e l'iterazione delle specifiche API, influenzando così il flusso di lavoro del team. Contiene funzionalità che lavorano fianco a fianco con riferimento a mock e aspetti collaborativi riguardanti l'emulazione relativa a scenari live. Gli strumenti di documentazione API di Stoplight sono potenzialmente utilizzati per mantenere riferimenti accurati e aggiornati. 
• SwaggerHub: Questa è una piattaforma progettata per la documentazione e la collaborazione API. Grazie ai modelli, l'utente può modificare lo stile e il formato della documentazione, il che può influenzare l'usabilità e la densità delle informazioni. Le funzionalità di controllo della versione di SwaggerHub sono di conseguenza legate a sviluppo API ciclo. Le funzionalità di collaborazione della piattaforma potrebbero estendere, supportare o facilitare l'interazione e la condivisione di informazioni tra gli utenti o in particolare tra i team.
• Apigee è una piattaforma specifica per Apigee è una piattaforma specificamente per la gestione delle API e le accompagna con una base di sicurezza e governance. Pertanto, nonostante la quantità di funzionalità che presenta, l'API potrebbe anche essere abbastanza complessa da richiedere ulteriori passaggi per l'implementazione da parte di team di piccole dimensioni o relativamente inesperti nella progettazione di API. Per alcune organizzazioni, il costo di Apigee potrebbe richiedere una valutazione approfondita del proprio budget. 

Il versionamento dell'API è la gestione delle modifiche all'interno di un'API nel tempo. È un po' come rilasciare una nuova edizione di un libro, in cui la versione precedente non viene scartata. Ciò è importante affinché la tua API rimanga compatibile e affinché qualsiasi applicazione che utilizza la tua API possa comunque essere eseguita mentre includi nuove funzioni, correzioni o persino una revisione completa della tua API.

Ecco le strategie di versionamento API comuni:

• Controllo delle versioni URI: È impostato nell'URL. (ad esempio, /v1/users, /v2/utenti). Questo è facile da comprendere ma può portare a diversi URL possibili.
• Versioning dell'intestazione: La versione viene trasmessa in un'intestazione della richiesta, ad esempio (ad esempio, API-Version: v2). Ciò rende gli URL puliti ma mette l'intestazione nelle mani dei client.
• Versioning dei parametri di query: Diventa un argomento aggiunto all'URL come stringa di query (ad esempio, /users?version=2). Meno difficile da implementare rispetto a quelli intermedi, ma non sempre chiaro.
• Negoziazione dei contenuti: Il client indica la versione richiesta del formato di risposta utilizzando Accetta intestazione. È flessibile ma leggermente più difficile da implementare rispetto a quella fissa.