Testa le API direttamente in Visual Studio!

Recentemente ho partecipato allo sviluppo di un progetto di integrazione tra la mia azienda e una società terza di servizi di telefonia. Questo progetto non era altro che un gateway di integrazione tra la nostra realtà e delle API REST messe a disposizione dal fornitore.

Il mio primo compito è stato quello di studiare la documentazione delle API del fornitore e predisporre un ambiente Postman da mettere a disposizione ai ragazzi del team per poter testare agilmente le varie chiamate durante i loro sviluppi.

In Postman ho configurato vari ambienti, le variabili che contenevano i dati, ecc. Ho scelto questo strumento perchè l’avevo sempre utilizzato e mi ero sempre trovato molto bene… fino a quando non mi sono ritrovato a doverlo condividere con altre 5 persone del mio team: bisognava (giustamente) pagare la licenza ma la mia azienda non voleva sostenere il costo. Alla fine il team si è ridotto e sono riuscito a condividere questa mia configurazione Postman con le persone che servivano.

Questo aspetto mi ha però spinto a cercare delle alternative al famoso omino arancione, nella mia realtà aziendale i requisiti volevo che fossero:

• Condivisione con N persone
• Possibilmente gratuito
• Gestione degli ambienti e di variabili di ambiente

La mia ricerca mi ha portato ad esplorare i file .http, introdotti con Visual Studio 2022 (versione 17.8) e che possiamo trovare nel template di default dei progetti api in .net 9!

Questo strumento consente di configurare e inviare richieste HTTP direttamente da Visual Studio, visualizzando le risposte senza la necessità di strumenti esterni. E’ possibile anche gestire diversi ambienti e variabili, con il vantaggio che questi file sono anche versionati!

In questo articolo vediamo come utilizzare e configurare questi file.

Prerequisiti

Visual Studio 2022 versione 17.8 o successiva

Creazione di un file .http

Se il nostro progetto non ha già un file .http possiamo aggiungerlo e organizzarlo come meglio crediamo. Per questo articolo ho creato un nuovo progetto ASP.NET Core Web API

Una volta creato il progetto potrete vedere che già di default avrete un file .http

Sintassi dei file .http

Partiamo dalle basi, un file .http può contenere una o più richieste HTTP. La sintassi generale per una richiesta è:

### Comment
MetodoHTTP URL VersioneHTTP
Intestazione1: Valore1
Intestazione2: Valore2

Corpo della richiesta (opzionale)

• MetodoHTTP: Il metodo HTTP da utilizzare (OPTIONS, GET, HEAD, POST, PUT, PATCH, DELETE, TRACE, CONNECT).
• URL: L’endpoint a cui inviare la richiesta.
• VersioneHTTP: (Opzionale) La versione HTTP da utilizzare (ad esempio, HTTP/1.1, HTTP/2, HTTP/3).
• Intestazioni: (Opzionali) Intestazioni HTTP aggiuntive per la richiesta.
• Corpo della richiesta: (Opzionale) Il payload da inviare con la richiesta, necessario per metodi come POST o PUT.

Vediamo di creare la nostra prima richiesta!

Esempio di richiesta GET

Sfruttiamo il controller di default WeatherForecastController per richiamare uno dei suoi endpoint

GET http://localhost:5249/weatherforecast/
Accept: application/json

Sopra alla nostra GET appariranno 2 pulsanti per testare la chiamata API: Send Request e Debug.

Se premiamo Send Request apparirà sulla destra un riquadro con alcuni dettagli della chiamata e la relativa risposta (il progetto deve essere avviato in questo caso), mentre se premiamo su Debug verrà avviato il progetto in configurazione Debug.

Esempio di richiesta POST con payload

### Api call to change city
POST http://localhost:5249/cities/change
Content-Type: application/json
{
    "CityCode": "Rome"
}

Utilizzo delle variabili

È possibile definire variabili all’interno dei file .http per riutilizzare valori comuni. Ipotizziamo di voler spostare l’endpoint base e la città in due variabili separate:

@baseAddress = http://localhost:5249
@city = "Rome"

### Api call to change city
POST {{baseAddress}}/cities/change
Content-Type: application/json

{
    "CityCode": "{{city}}"
}

Le variabili sono definite utilizzando la sintassi @nomeVariabile = valore e richiamate con {{nomeVariabile}}.

Gestione degli ambienti

Nel mio caso avevo la necessità di creare 3 diverse configurazioni, una per lo sviluppo, una per test e una per l’ambiente di produzione. Per farlo tramite .http possiamo andare a creare un file specifico dove andare a configurare i vari ambienti, il file avrà questo nome: http-client.env.json e dovrà essere creato nella stessa cartella del file .http (in caso contrario VS lo cercherà a ritroso nella carie cartelle, fino alla radice principale del progetto). Al suo interno andremo a definire un json per descrivere gli ambienti.

{
  "sviluppo": {
    "baseUrl": "https://localhost:5001"
  },
  "test": {
    "baseUrl": "https://api-test.com"
  },
  "produzione": {
    "baseUrl": "https://api.com"
  }
}

In Visual Studio, è possibile selezionare l’ambiente desiderato tramite un menu a discesa nell’editor .http, in alto a destra.

Ora che abbiamo definito gli endpoint dei vari ambienti eliminiamo la variabile @baseAddress definita nel file .http e sostituiamola con quella dell’ambiente selezionato (baseUrlAddress):

@city = Rome

### Api call to change city
POST {{baseUrlAddress}}/weatherforecast/cities/change
Content-Type: application/json

{
    "CityCode": "{{city}}"
}

Variabili di ambiente condivise

Nel file http-client.env.json possiamo anche definire delle variabili condivise tra i vari ambienti, in questo esempio andiamo a creare la variabile “changeCityEndpoint“.

Notate inoltre che è possibile eseguire un override della variabile in una configurazione specifica, come ad esempio nella configurazione “produzione” alla linea 13.

{
  "$shared": {
    "changeCityEndpoint": "/weatherforecast/cities/change"
  },
  "sviluppo": {
    "baseUrlAddress": "https://localhost:7100"
  },
  "test": {
    "baseUrlAddress": "https://api-test.com"
  },
  "produzione": {
    "baseUrlAddress": "https://api.com",
    "changeCityEndpoint": "/api/weatherforecast/cities/change"
  }
}

@city = Rome

### Api call to change city
POST {{baseUrlAddress}}{{changeCityEndpoint}}
Content-Type: application/json

{
    "CityCode": "{{city}}"
}

Variabili di ambiente private

In alcuni casi vorremmo poter utilizzare una configurazione nostra che non vogliamo condividere con altri o aggiungere al repository. Per farlo basterà creare un file di ambiente che terminerà con .user. (i file .user sono esclusi automaticamente dal versionamento).

Creiamo un file chiamato http-client.env.json.user (nella stessa directory dove è presente il file http-client.env.json), graficamente sarà posizionato da Visual Studio all’interno del file di environment.

All’interno possiamo definire solamente le variabili che ci interessano, per esempio:

{
  "sviluppo": {
    "baseUrlAddress": "https://localhost:5000"
  }
}

Conclusioni

In questo articolo abbiamo visto come andare a testare delle API REST direttamente da Visual Studio, configurando i file .http ed i relativi file di ambiente. Il vantaggio di questo approccio è che non dobbiamo dipendere da strumenti esterni ma soprattutto i file che produrremo saranno inclusi nel nostro repository di versionamento.

Spero che la lettura sia stata piacevole, nel caso vogliate approfondire ulteriormente vi rimando alla guida ufficiale di Microsoft sull’argomento.

Grazie ancora per la lettura, a presto!