Skip to content

Commit

Permalink
Bump version to 0.20.0
Browse files Browse the repository at this point in the history
Signed-off-by: Huachao Mao <[email protected]>
  • Loading branch information
Huachao committed Oct 8, 2018
1 parent 1b92fbb commit d297d5a
Show file tree
Hide file tree
Showing 5 changed files with 31 additions and 11 deletions.
14 changes: 14 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,17 @@
## 0.20.0 (2018/10/8)
* __Feature__: [Support file variables reference request variables](https://github.com/Huachao/vscode-restclient/issues/181)
* __Feature__: [Support resolve the full response body regardless of the response content type](https://github.com/Huachao/vscode-restclient/issues/188)
* __Bug Fix__: [Fix Https proxy issue](https://github.com/Huachao/vscode-restclient/issues/255)
* __Bug Fix__: [Reload configuration when switching active text editor](https://github.com/Huachao/vscode-restclient/issues/245)
* __Bug Fix__: Fix incorrect http symbol range
* __Bug Fix__: Ensure response saving directory existence before saving
* __Improvement__: Add icon for response webview tab
* __Improvement__: [Switch JSON formatting library from `jsonc-parser` to `js-beautify`](https://github.com/Huachao/vscode-restclient/pull/233) ([@ygraber](https://github.com/ygraber))
* __Improvement__: [Treat the mime type of response body is `application/json` if the body itself is a `JSON` string](https://github.com/Huachao/vscode-restclient/issues/239)
* __Improvement__: [Unset gzip setting to avoid adding `Accept-Encoding` header automatically](https://github.com/Huachao/vscode-restclient/issues/256)
* __Improvement__: [Upgrade applicationinsights to latest version to avoid monkey patching](https://github.com/Huachao/vscode-restclient/issues/260)


## 0.19.1 (2018/8/7)
* __Bug Fix__: [Make Azure AAD Auth respect the audience](https://github.com/Huachao/vscode-restclient/issues/225)
* __Bug Fix__: [Fix curl command can't be run on Windows](https://github.com/Huachao/vscode-restclient/issues/227)
Expand Down
22 changes: 14 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -323,7 +323,7 @@ Environments and including variables are defined directly in `Visual Studio Code
## Variables
We support two types of variables, one is __Custom Variables__ which is defined by user and can be further divided into __Environment Variables__, __File Variables__ and __Request Variables__, the other is __System Variables__ which is a predefined set of variables out-of-box.

The reference syntax of system and custom variables types has a subtle difference, for the former the syntax is `{{$SystemVariableName}}`, while for the latter the syntax is `{{CustomVariableName}}`, without preceding `$` before variable name. The definition syntax and location for different types of custom variables are obviously different. Notice that when the same name used for custom variable, request variables takes higher resolving precedence over file variables, file variables takes higher precedence over environment variables.
The reference syntax of system and custom variables types has a subtle difference, for the former the syntax is `{{$SystemVariableName}}`, while for the latter the syntax is `{{CustomVariableName}}`, without preceding `$` before variable name. The definition syntax and location for different types of custom variables are obviously different. Notice that when the same name used for custom variables, request variables takes higher resolving precedence over file variables, file variables takes higher precedence over environment variables.

### Custom Variables
Custom variables can cover different user scenarios with the benefit of environment variables, file variables, and request variables. Environment variables are mainly used for storing values that may vary in different environments. Since environment variables are directly defined in Visual Studio Code setting file, they can be referenced across different `http` files. File variables are mainly used for representing values that are constant throughout the `http` file. Request variables are used for the chaining requests scenarios which means a request needs to reference some part(header or body) of another request/response in the _same_ `http` file, imagine we need to retrieve the auth token dynamically from the login response, request variable fits the case well. Both file and request variables are defined in the `http` file and only have __File Scope__.
Expand Down Expand Up @@ -353,7 +353,9 @@ Authorization: {{token}}
```

#### File Variables
For file variables, the definition follows syntax __`@variableName = variableValue`__ which occupies a complete line. And variable name __MUST NOT__ contains any spaces. As for variable value, it can be consist of any characters, even whitespaces are allowed for them (Leading and trailing whitespaces will be stripped). If you want to preserve some special characters like line break, you can use the _backslash_ `\` to escape, like `\n`. File variables can be defined in a separate request block only filled with variable definitions, as well as define request variables before any request url, which needs an extra blank line between variable definitions and request url. However, no matter where you define the file variables in the `http` file, they can be referenced in any requests of whole file. For file variables, you can also benefit from some `Visual Studio Code` features like _Go To Definition_ and _Find All References_. Below is a sample of file variable definitions and references in an `http` file.
For file variables, the definition follows syntax __`@variableName = variableValue`__ which occupies a complete line. And variable name __MUST NOT__ contains any spaces. As for variable value, it can be consist of any characters, even whitespaces are allowed for them (Leading and trailing whitespaces will be stripped). If you want to preserve some special characters like line break, you can use the _backslash_ `\` to escape, like `\n`. File variable value can even contain references to the [request variables](#request-variables) like `@token = {{loginAPI.response.body.token}}`.

File variables can be defined in a separate request block only filled with variable definitions, as well as define request variables before any request url, which needs an extra blank line between variable definitions and request url. However, no matter where you define the file variables in the `http` file, they can be referenced in any requests of whole file. For file variables, you can also benefit from some `Visual Studio Code` features like _Go To Definition_ and _Find All References_. Below is a sample of file variable definitions and references in an `http` file.

```http
@host = api.example.com
Expand All @@ -379,7 +381,7 @@ Content-Type: {{contentType}}
#### Request Variables
For request variables, they are similar to file variables in some aspects, like scope and definition location. However, they have some obvious differences. The definition syntax of request variables is just like a single-line comment, and follows __`// @name requestName`__ or __`# @name requestName`__ just before the desired request url. You can think of request variable as attaching a *name metadata* to the underlying request, and this kind of requests can be called with **Named Request**, while normal requests can be called with **Anonymous Request**. Other requests can use `requestName` as an identifier to reference the expected part of the named request or its latest response. Notice that if you want to refer the response of a named request, you need to manually trigger the named request to retrieve its response first, otherwise the plain text of variable reference like `{{requestName.response.body.$.id}}` will be sent instead.

The reference syntax of a request variable is a bit more complex than other kinds of custom variables. The request variable reference syntax follows `{{requestName.(response|request).(body|headers).(JSONPath|XPath|Header Name)}}`. You have two reference part choices of the response or request: *body* and *headers*. For *body* part, it only works for `JSON` and `XML` responses, you can use [JSONPath](http://goessner.net/articles/JsonPath/) and [XPath](https://developer.mozilla.org/en-US/docs/Web/XPath) to extract specific property or attribute. For example, if a JSON response returns body `{"id": "mock"}`, you can set the JSONPath part to `$.id` to reference the id. For *headers* part, you can specify the header name to extract the header value. Additionally, the header name is *case-insensitive*.
The reference syntax of a request variable is a bit more complex than other kinds of custom variables. The request variable reference syntax follows `{{requestName.(response|request).(body|headers).(*|JSONPath|XPath|Header Name)}}`. You have two reference part choices of the response or request: *body* and *headers*. For *body* part, you can use `*` to reference the full response body, and for `JSON` and `XML` responses, you can use [JSONPath](http://goessner.net/articles/JsonPath/) and [XPath](https://developer.mozilla.org/en-US/docs/Web/XPath) to extract specific property or attribute. For example, if a JSON response returns body `{"id": "mock"}`, you can set the JSONPath part to `$.id` to reference the id. For *headers* part, you can specify the header name to extract the header value. Additionally, the header name is *case-insensitive*.

> If the *JSONPath* or *XPath* of body, or *Header Name* of headers can't be resolved, the plain text of variable reference will be sent instead. And in this case, diagnostic information will be displayed to help you to inspect this. And you can also hover over the request variables to view the actual resolved value.
Expand All @@ -396,9 +398,11 @@ name=foo&password=bar
###
@authToken = {{login.response.headers.X-AuthToken}}
# @name createComment
POST {{baseUrl}}/comments HTTP/1.1
Authorization: {{login.response.headers.X-AuthToken}}
Authorization: {{authToken}}
Content-Type: application/json
{
Expand All @@ -407,20 +411,22 @@ Content-Type: application/json
###
@commentId = {{createComment.response.body.$.id}}
# @name getCreatedComment
GET {{baseUrl}}/comments/{{createComment.response.body.$.id}} HTTP/1.1
Authorization: {{login.response.headers.X-AuthToken}}
GET {{baseUrl}}/comments/{{commentId}} HTTP/1.1
Authorization: {{authToken}}
###
# @name getReplies
GET {{baseUrl}}/comments/{{createComment.response.body.$.id}}/replies HTTP/1.1
GET {{baseUrl}}/comments/{{commentId}}/replies HTTP/1.1
Accept: application/xml
###
# @name getFirstReply
GET {{baseUrl}}/comments/{{createComment.response.body.$.id}}/replies/{{getReplies.response.body.//reply[1]/@id}}
GET {{baseUrl}}/comments/{{commentId}}/replies/{{getReplies.response.body.//reply[1]/@id}}
```

Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
"name": "rest-client",
"displayName": "REST Client",
"description": "REST Client for Visual Studio Code",
"version": "0.19.1",
"version": "0.20.0",
"publisher": "humao",
"author": {
"name": "Huachao Mao",
Expand Down
2 changes: 1 addition & 1 deletion src/models/httpVariableResolveResult.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ export const enum ResolveState {

export const enum ResolveErrorMessage {
NoRequestVariablePath = 'Request variable path is not provided',
InvalidRequestVariableReference = 'Incorrect request variable reference syntax, it should be "variableName.(response|request).(headers|body).(headerName|JSONPath|XPath)"',
InvalidRequestVariableReference = 'Incorrect request variable reference syntax, it should be "variableName.(response|request).(headers|body).(headerName|JSONPath|XPath|*)"',
SystemVariableNotExist = 'System variable does not exist',
EnvironmentVariableNotExist = 'Environment variable does not exist',
FileVariableNotExist = 'File variable does not exist',
Expand Down
2 changes: 1 addition & 1 deletion src/utils/httpElementFactory.ts
Original file line number Diff line number Diff line change
Expand Up @@ -152,7 +152,7 @@ export class HttpElementFactory {
ElementType.RequestCustomVariable,
null,
v,
new SnippetString(`{{${name}.\${1|request,response|}.\${2|headers,body|}.\${3:Header Name, JSONPath or XPath}}}`)));
new SnippetString(`{{${name}.\${1|request,response|}.\${2|headers,body|}.\${3:Header Name, *(Full Body), JSONPath or XPath}}}`)));
}

// add urls from history
Expand Down

0 comments on commit d297d5a

Please sign in to comment.