OpenAPI
OpenAPI descrive interfacce HTTP in forma leggibile dalle macchine, con percorsi, parametri e risposte. La descrizione deve corrispondere al servizio.
Registrare un contratto API HTTP comprensibile
OpenAPI è uno standard per descrivere API HTTP. Una descrizione OpenAPI registra, tra l’altro, percorsi, operazioni, parametri e strutture delle risposte offerte. Può essere rappresentata in JSON o YAML. Il linguaggio di descrizione non dipende dal linguaggio di programmazione usato per realizzare il servizio.
Un’azienda di software fittizia prevede GET /projects/{projectId} per il proprio portale di progetti. La descrizione deve definire projectId come parametro del percorso; la risposta riuscita 200 deve includere, tra gli altri, il campo testuale name. Anche le risposte di errore note fanno parte del contratto. Percorso e campi sono nostri esempi di progettazione, non un documento OpenAPI completo né un servizio esistente.
Il gruppo frontend può così capire quali informazioni inviare e quali risposte gestire. Il solo file non mostra però se l’implementazione in funzione rispetta il contratto. Prima della consegna andrebbero confrontate descrizione e risposte effettive, compresi gli errori. Va concordato anche il significato di name: una stringa con il tipo corretto non spiega quale nome contenga il campo.
Fonti
Termini correlati
- APIUn’API definisce come un programma può usare funzioni o dati messi a disposizione da un altro programma.
- RESTREST definisce regole di architettura per interfacce distribuite. Risorse, richieste senza stato e collegamenti fanno parte dell’approccio.
- Server-Sent EventsSSE trasmette notifiche testuali dal server al client via HTTP, per esempio sull’avanzamento di un lavoro in background.
- ETagUn ETag identifica una specifica versione della rappresentazione di una risorsa HTTP e consente letture o modifiche condizionali.
- Cross-Origin Resource SharingCORS regola l’accesso del browser alle risposte di un’altra origine. Non sostituisce l’autenticazione né il controllo delle autorizzazioni nell’API.
- Electronic Data InterchangeEDI trasferisce documenti aziendali strutturati fra sistemi. Formato, profilo del partner, corrispondenze dei dati e risposte devono essere coerenti.
Il vostro progetto con ASES
Descriveteci il vostro progetto. Vi ricontatteremo con una prima valutazione.