Progettazione di API

Passare dai requisiti a un'API

Come la maggior parte delle tecnologie, un'API è una soluzione a un problema. Per progettare l'API corretta, è necessario assicurarsi che il problema che si sta affrontando sia chiaramente definito rispondendo alle seguenti domande:

• Chi sono i consumatori target di questa API?
• Che tipo di informazioni manipoleranno i consumer tramite l'API?
• Quali azioni eseguiranno i consumer sull'API?

Ad esempio, se sei un'azienda di food delivery, potresti voler creare un'API per la tua rete di partner che consenta loro di consultare ed effettuare ricerche in un database di ristoranti per i quali fornisci un servizio di consegna.

In questo esempio, la tua API si rivolge ai partner della tua azienda. Dovranno manipolare i dati relativi ai ristoranti ed eseguire query di ricerca sui dati, con determinate funzionalità di filtro e ordinamento.

Un altro esempio: se sei un'azienda SaaS di calendari, potresti voler sviluppare un'API in modo che altri sviluppatori front-end in tutto il mondo possano creare nuove applicazioni mobile e web basate sul tuo sistema di calendari.

Pensare ai consumatori della tua API è il primo passo per offrire loro una buona esperienza di sviluppo. Questo aiuterà la tua API a distinguersi e ad aumentare i livelli di coinvolgimento.

Gli elementi che compongono un'API

Esistono quattro concetti chiave utilizzati nella progettazione di un'API:

• Una risorsa è un elemento con cui i tuoi consumer interagiranno tramite la tua API. Le risorse sono identificate in modo univoco da un percorso che, combinato con l'endpoint dell'API, fornisce un indirizzo univoco per una risorsa sul Web. Ad esempio, Calendars è il nome di una risorsa che corrisponde a un elenco di calendari e il suo percorso è /calendars.
• Un'Operazione è l'azione che può essere eseguita sulle tue risorse. Le operazioni più comuni sono GET (lettura), POST (creazione), PUT (aggiornamento) e DELETE. Ad esempio, List all Calendars è il nome di un'operazione che utilizza il metodo GET sulla risorsa Calendars.
• Un tipo di dati è una descrizione dei dati effettivi scambiati attraverso la rete. Ad esempio, Calendar è il nome di un tipo di dati che descriverà tutte le proprietà di un Calendar, come il nome, il proprietario e un riferimento agli eventi che gli appartengono. L'operazione List all Calendars restituisce un elenco di tipi di dati Calendar.
• Un componente è un elemento che può essere riutilizzato in tutta la definizione dell'API. Ad esempio, se devi utilizzare lo stesso parametro di query in diverse operazioni, puoi crearlo come componente e farvi riferimento in tutte le operazioni necessarie.

Ci sono altri elementi utili che compongono un'API:

• Un Endpoint è il punto di ingresso principale per la tua API sul Web. Un endpoint è composto da uno schema come HTTPS e da un host come www.calendar-api.com.
• Un blocco Testo può essere utilizzato per inserire liberamente qualsiasi testo (incluso il markdown) che può essere posizionato ovunque nella progettazione della tua API. Utilizza i blocchi di testo per spiegare argomenti trasversali come l'autenticazione e la gestione degli errori.
• Una sezione viene utilizzata per raggruppare in modo significativo risorse e tipi di dati. Utilizzali per rendere il design della tua API più chiaro e più intuitivo per gli sviluppatori. È possibile effettuare il trascinamento degli elementi nelle sezioni nel pannello di sinistra ed è anche possibile riordinare le sezioni tra loro.

In Contratti API, sarà possibile creare questi elementi dal menu Crea nuovo nell'angolo in alto a destra.

Gli URL del server vengono creati nella schermata delle informazioni generali. Un URL del server può essere Pubblicato o Non pubblicato. Se è pubblicato, appare nella Live Documentation.