What are HTTP files and how to use them in Visual Studio to test APIs

.http files are simple and powerful way to provide an easy and convenient way to test external or internal APIs. It’s just like running a mini Postman in your own solution. This article explains how to create and use HTTP files specific to Visual Studio.

What are .HTTP files and how it works?

.http files are used to define API calls. Later, developers can use them test and interact with APIs directly from their development environment. Typically, developer will go out of visual studio (or any IDE) to test API, this includes using Postman, APIDog etc. Though, Postman or any other tool offers more comprehensive approach for API management, like UI to create, organize and documenting, .HTTP files are great for quick testing and integration within codebases.

HTTP files are typically executed by extensions within an IDE, like the REST Client extension in Visual Studio Code or similar tools in JetBrains IDEs. These extensions parse the file and send the HTTP requests to the specified endpoints, then display the responses directly in the editor.

Creating .HTTP files

Once you have created your project, right click the your project from Solution Explorer and select Add -> New Item (or use keyboard shortcut Control+Shift+A). In the Add dialog, search for http:

Enter desire name and click Add button.

Create Request

The syntax to define HTTP request is as following:

<HttpMethod> <URL> <HttpVersion>

HttpMethod: This is typically, GET, PUT, POST etc. And it generally defines the purpose of the HTTP call.

URL: This is the endpoint where the request will be sent.

HttpVersion: This is an optional argument is used to define the version

You can separate multiple requests uisng “###” as delimiter. Here is an example:

GET https://jsonplaceholder.typicode.com/todos/1
###
GET https://jsonplaceholder.typicode.com/posts/1
###
POST https://jsonplaceholder.typicode.com/posts

Adding Headers

Some requests requires passing header to the request. We can add header in key:value format, right after defining the request. Make sure not to have any blank lines between request and header.

GET https://jsonplaceholder.typicode.com/posts
Accept:*/*

Request body

POST or PUT requires to pass body, so that server can process the request. Here is how we can pass one:

POST https://jsonplaceholder.typicode.com/posts
Content-Type: application/json

[
  {
    "userId": 1,
    "id": 1,
    "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
    "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
  }
]
###

Using Variables

Let’s say we have multiple APIs and they use same URL base or we have a scenario where same parameter value is being used by multiple APIs. If we define like above and if there is a change in the value then it will be a daunting task to update everywhere. Variables are useful when we have multiple places using the same value. Here is an example:

# For more info on HTTP files go to https://aka.ms/vs/httpfile

#This is  comment
//This is also a comment

//Note that we don't put variable value in double quotes

@hostname = https://jsonplaceholder.typicode.com
@todoPath = todos
@postPath = posts

//Note that we don't use @ before variable name while using it

GET {{hostname}}/{{todoPath}}/1

###
GET {{hostname}}/{{postPath}}/1

###
POST {{hostname}}/{{postPath}}
Content-Type: application/json

[
  {
    "userId": 1,
    "id": 1,
    "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
    "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
  }
]

Using Environment Files

Using variable is good, however, in a typical scenario, the values differ base on the environment. For example, we may change the host name to our staging server or QA server based on testing requirements. To address this we can use environment files. Let’s create one in our project.

1. Add JSON file in either same folder where .http file is or in any of it’s parent folder.
2. The name of the file must be “http-client.env.json”
3. Close and re-open your project or .http file after adding the environment file.

Here is a sample file content:

{
  "local": {
    "HostAddress": "https://localhost:44320"
  },
  "qa": {
    "HostAddress": "https://qa.server.com"
  }
}

Note that “local”, “qa” refers to environment and under that we have keys with value.

After following above steps, you should be able to see environment selector on top right while you are in .http file viewing:

To use the values in the environment file, simply refer the key. No need to import the file in our .http file. Here is how it will look if we want to use HostAddress.

# For more info on HTTP files go to https://aka.ms/vs/httpfile

#This is  comment
//This is also a comment

//Note that we don't put variable value in double quotes

//@hostname = https://jsonplaceholder.typicode.com
@todoPath = todos
@postPath = posts

GET {{HostAddress}}/{{todoPath}}/1

###
GET {{HostAddress}}/{{postPath}}/1

###
POST {{HostAddress}}/{{postPath}}
Content-Type: application/json

[
  {
    "userId": 1,
    "id": 1,
    "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
    "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
  }
]

Using .env files

Modern applications use .env file to store environment specific values, in those cases, creating separate json file doesn’t make any sense. Further, we have to be mindful to keep both files in synch. .HTTP files are more powerful then we think, they can access .env file out-of-the-box. Here is an example:

GET {{HostAddress}}{{Path}}
X-UserName: {{$dotEnv USERNAME}}

Here we are accessing “USERNAME” from .env file.

Reading Environment variable

We often store and read some details from environment variables. This may include environment specific sensitive information, like secret key. To access those in .http file we can use $processEnv. Here is an example:

GET {{HostAddress}}{{Path}}
X-UserName: {{$processEnv secretKey}}

Conclusion

.HTTP files are really powerful and helpful in setting up easy, fast and reliable testing for APIs (local or third-party). Further, we can check-in the file in source code to share between multiple developers. This is extremely valuable when we onboard a new developer or add new API and make sure other developers are aware on how to call it.