Progettazione di API

Passare dai requisiti a un'API

Come la maggior parte delle tecnologie, un'API è la soluzione a un problema. Per progettare l'API giusta, è 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 consumatori tramite l'API?
• Quali azioni eseguiranno i consumatori sull'API?

Ad esempio, se sei un'azienda di consegna di cibo, potresti voler creare un'API per la tua rete di partner che consenta loro di sfogliare e cercare in un database di ristoranti per i quali fornisci un servizio di consegna.

In questo esempio, la tua API è rivolta ai partner della tua azienda. Avranno bisogno di manipolare i dati sui ristoranti ed eseguire query di ricerca sui dati, con determinate capacità di filtraggio e ordinamento.

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

Pensare ai consumatori della tua API è il primo passo per fornire 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

Ci sono quattro concetti chiave utilizzati durante la progettazione di un'API:

• Una Risorsa è un elemento con cui i tuoi consumatori 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 che vengono scambiati sulla rete. Ad esempio, Calendar è il nome di un tipo di dati che descriverà tutte le proprietà di un Calendario, come il suo 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 è necessario utilizzare lo stesso parametro di query in diverse operazioni, è possibile 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 di Testo può essere utilizzato per inserire liberamente qualsiasi testo (incluso markdown) che può essere posizionato ovunque nella progettazione della tua API. Usa 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. Usale per rendere la progettazione della tua API più chiara e più adatta agli sviluppatori. Puoi usare il trascinamento per spostare gli elementi nelle sezioni nel pannello di sinistra e puoi anche riordinare le sezioni tra loro.

In API Designer, sarai in grado di 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.