【Translation】HTTP file updates request variable

Many users require support for request variables to add support for Visual Studio's HTTP files. Using the request variable, you can send an HTTP request and then use the data from the response or request in any subsequent request sent from the HTTP file. We also added support for the shared environment $shared , which enables you to share variables in different environments. In this article, we will outline support for newly added request variables, etc. All features listed in this article are included in Visual Studio 2022 17.12+.

Request variables

When using the API, a value is usually taken from the endpoint and then used in subsequent requests. This can be achieved by using request variables. We have documentation for requesting variables, but we will also discuss everything here. A more common scenario for using request variables is when you call an endpoint to authenticate the API and get a token that can be used for future requests. The following example request is a TodoApi example from David Fowler. The API has an endpoint where you can create a new user by providing a username and password. This is the endpoint where we are making the request.

@username = bloguser
# login and save the response as "login"
# @name login
POST {{TodoApi_HostAddress}}/users/token
Content-Type: application/json
{
  "username": "{{username}}",
  "password": "{{password}}"
}
###

In this case, the username is defined in the HTTP file, but the password is stored securely using HTTP Environments. The following request is sent to the /users/token endpoint, and we pass the username and password as part of the HTTP request body. Make it a request variable (sometimes called a named request), the special thing is the line above the comment.

# @name login

After you send this request in Visual Studio, you can get the value from the response or request. In the following code snippet, you can see how we use the request variable in the login to access the token returned as part of the response when the response is submitted. The login response contains a token. Now that we are logged in, we can create a TODO item with the following request.

# Create a TODO item
# @name todo1
POST {{TodoApi_HostAddress}}/todos
Authorization: Bearer {{.$.token}}
Content-Type: application/json

{
  "title": "Write blog post"
}
###

In this request, we extract the token value and use it to specify the value of the Authorization header. The syntax is {{.$.token}}. Let's take a closer look at the grammar.

{{.$.token}}

The following table summarizes the syntax for using values ​​from requested variables:

For the example request above, we extract the token from the response and pass it as the request's header to the /todos endpoint. After sending this request, the returned result is as follows:

{
  "id": 36,
  "title": "Write blog post",
  "isComplete": false
}

Now that we have created a TODO project, we can update the project with the request below. If you notice that the above request declares a request variable named todo1, then we can use it to reference the value in the response or request. Let's update the title and add "today" to the end of the current title. The following request will update the TODO item. We will use PUT because this is an update to existing items.

PUT {{TodoApi_HostAddress}}/todos/{{.$.id}}
Authorization: Bearer {{.$.token}}
Content-Type: application/json

{
  "id": {{.$.id}},
  "title": "{{.$.title}} today",
  "isComplete": {{.$.isComplete}}
}
###

In this request, we populate the body of the PUT request with data from the original todo1 request. Note that the title property appends "today" to the end of an existing title. After sending this request, the result is:

{
  "id": 36,
  "title": "Write blog post today",
  "isComplete": false
}

Here you can see that the title of the blog post has been successfully updated. In these examples, I showed how to handle "flat" JSON results, but you can use any JSONPath expression to extract data from the response or request body. If the endpoint returns XML, use the XPath expression instead of JSONPath. Let's continue to discuss support for $shared.

$shared

When using an HTTP environment, you can define multiple different environments for HTTP requests. For example, you can create a development environment that references a locally running API, and create a test environment when you want to send a request to a remote test environment. In these cases, you may want to declare a variable that is available for all environments. This is exactly what the new $shared environment is going to do. The HTTP environment is defined in a file named .json or . If you create an environment called $shared, these variables will be available in any environment. If a variable is declared in both $shared and standard environments, then the values ​​defined in the standard environment will take precedence. Here is an example HTTP environment file containing a $shared environment and two standard environments.

{
  "$shared": {
    "message": "Default msg from Shared",
    "username": "httpfile-user",
    "hosturl": "/api/sample"
  },
  "dev": {
    "hosturl": "http://localhost:5000/api/sample"
  },
  "prod": {
    "message": "Message from prod environment"
  }
}

This is a very basic HTTP environment file, and in addition to $shared, we also define the dev and prod environments. In the dev environment, the value of hosturl has been customized to point to localhost, while the value of message is customized in the prod environment. To illustrate how this works, we will use third-party open source websites. It is a great tool for API developers. We will create an HTTP file, make a request to it, and have it return the provided value. We will use the /headers endpoint so that httpbin will echo the header we sent to it. Here is the request we will send:

GET /headers
X-Message: {{message}}
X-User: {{username}}
X-Hosturl: {{hosturl}}

###

This request uses variables defined in the HTTP environment in the request sent to. As a reminder, you can select environment in the drop-down menu in the upper right corner of the HTTP file editor. I set the environment to dev and the result from 'is as follows:

{
  "headers": {
    "X-Hosturl": "http://localhost:5000/api/sample",
    "X-Message": "Default msg from Shared",
    "X-User": "httpfile-user"
  }
}

In the response, I deleted some irrelevant titles. We can see that these values ​​are being filled as expected. The value of hosturl is the localhost specified in the dev environment, and the other values ​​are from $shared. When we switch the environment to prod and send the same request, the response looks like this:

{
  "headers": {
    "X-Hosturl": "/api/sample",
    "X-Message": "Message from prod environment",
    "X-User": "httpfile-user"
  }
}

The values ​​of hosturl and message have been changed. The values ​​of hosturl and username are from $shared, and the message is from the values ​​provided in the prod environment. If you send a request without selecting an environment, the value in $shared will be available. Now that we have covered new support for $shared, we are now closing this blog post.

summary

In this article, we introduce two new features of HTTP files, request variables and $shared in HTTP environments. With support for request variables, you can now create a "chained" request that gets the value from previous requests. This will allow you to practice the API in a more practical way than before. Additionally, with $shared, you can now share variables across environments, making it easier for you to use an HTTP environment. If you are not familiar with HTTP files, check the documentation for more information.

This update is inspired by feedback from users like you. You can share feedback with us through the developer community: By reporting bugs or issues and share your suggestions for new features or improvements to existing features.

Original text connection: /visualstudio/http-file-updates-for-request-variables-and-more/