JetBrains Rider 2018.2 Help

HTTP Client in JetBrains Rider Code Editor

When testing a web service, you can create, edit, and execute HTTP Requests directly in the JetBrains Rider

HTTP Requests are stored in the http and rest files and are marked with the HTTP file icon icon.

Support for HTTP files inside the JetBrains Rider code editor includes the following features:

If necessary, configure the Proxy settings on the HTTP Proxy page of the Settings/Preferences (Ctrl+Alt+S) dialog.

Creating an HTTP request file

You can work with HTTP requests either from scratch files or from physical files of the HTTP Request type.

Scratch files can be used to test HTTP requests during development. A scratch file is not stored inside a project, so JetBrains Rider can modify it and add additional information about the request. When an HTTP request is executed from a scratch file, the link to the response output file is added below the request and at the top of the requests history file.

To create an HTTP requests scratch file

  • Press Ctrl+Shift+Alt+Insert and select HTTP Request.

Physical files can be used for documenting, testing and validating HTTP requests. A physical file is stored inside your project, and JetBrains Rider will not modify it. When an HTTP request is executed from a physical file, this file is not modified. Information about the executed request with the link to the response output file is added to the top of the requests history file.

To create a physical HTTP requests file

  • On the File menu, point to New, and then click HTTP Request.

You can use the Move refactoring (Ctrl+R, O) to move HTTP requests from scratches to physical files, as well as between physical files.

To move an HTTP request

  1. In the editor, position the caret at the request to be moved and do one of the following:
    • On the main menu, or on the context menu, choose Refactor | Move.

    • Press Ctrl+R, O.

  2. In the dialog box that opens, click browse to select the file or type the full path to the file you want to move the request to. Note that you can specify the name of a non-existing file, in which case a new file with the provided name will be created automatically.

Composing an HTTP request

You can type HTTP requests directly in the created HTTP request file using the following general syntax:

Method Request-URI HTTP-Version Header-field: Header-value Request-Body

JetBrains Rider uses the HTTP request in Editor format, which provides a simple way to create, execute, and store information about HTTP requests. To get an overview of its possibilities, you can explore the HTTP Requests Collection, which is a handful selection of composed requests.

To open a request from the HTTP Requests Collection

  1. Click Open HTTP Requests Collection icon in the top-right corner of the editor or choose Tools | HTTP Client | Open HTTP Requests Collection in the main menu.

  2. In the pop-up menu, select the HTTP Requests collection you wish to open:

    Open HTTP Requests Collection popup

To speed up composing HTTP requests, use live templates. For example, gtr expands to a simple GET request; mptr expands to a multipart/form-data POST request.

Examples: Exploring the HTTP request in Editor syntax

The following examples demonstrate the HTTP request in Editor format features in more detail:

  • You can omit the request method and specify only the URI to use GET by default. Comment lines can be started either with // or #:

    // A basic request http://example.com/a/
  • To mark the end of a request and compose another one in the same file, type ###:

    // A basic request http://example.com/a/ ### // Longer request with method GET http://example.com:8080/api/html/get?id=123&value=content

    It may be more convenient to break long requests into several lines. Note that in this case all query string lines but the first one must be indented, for example:

    // Using line breaks with indent GET http://example.com:8080 /api /html /get ?id=123 &value=content
  • To access the target web-service with basic or digest authentication, you can generate an Authorization header as follows:
    // Basic authentication GET http://example.com Authorization: Basic username password ### // Digest authentication GET http://example.com Authorization: Digest username password

    Similarly to other HTTP request's elements, the provided username and password can be parameterized by means of environment variables.

  • To specify the request message body, prepend it with a blank line. You can either provide the request body in place or read it from a file.

    • If you set the Content-Type header field value to one of the languages supported by JetBrains Rider, then the corresponding language fragment will be auto-injected into the HTTP request message body. If Content-Type is not specified, you can inject a language fragment manually. For more information, see Web-Specific Language Injections.

    • To read the request body from a file, type the < symbol followed by the path to the file.

    // The request body is provided in place POST http://example.com:8080/api/html/post HTTP/1.1 Content-Type: application/json Cookie: key=first-value { "key" : "value", "list": [1, 2, 3] } ### // The request body is read from a file POST http://example.com:8080/api/html/post Content-Type: application/json < ./input.json
  • You can execute HTTP requests with the multipart/form-data content type. To send a file as part of the multipart/form-data message, include the filename parameter in the Content-Disposition header.

    POST http://example.com/api/upload HTTP/1.1 Content-Type: multipart/form-data; boundary=boundary --boundary Content-Disposition: form-data; name="first"; filename="input.txt" // The 'input.txt' file will be uploaded < ./input.txt --boundary Content-Disposition: form-data; name="second"; filename="input-second.txt" // A temporary 'input-second.txt' file with the 'Text' content will be created and uploaded Text --boundary Content-Disposition: form-data; name="third"; // The 'input.txt' file contents will be sent as plain text. < ./input.txt --boundary--

Using environment variables

When composing an HTTP request, you can parametrize its elements using environment variables. For example, instead of providing the host name in your request explicitly, you can use the {{host}} placeholder. Then you define a set of environment variables in your project holding the desired host definitions. When you execute the request, JetBrains Rider will provide a choice of defined environments, in our case, the host to send the request to:

run_request_in_env

The selected environment will be used as the default one when viewing structure of the request and opening the request in the browser.

The name of a variable can be arbitrary, but may only contain letters, digits, the underscore symbols (_), or the hyphen symbols (-). A variable can hold the values for the following request components:

  • Request host, port, and path

  • Query parameter or value

  • Header value

  • Arbitrary values provided directly inside the request body or supplied in an external file.

Environment variables are defined in the environment files, which must be stored inside the project:

  • The rest-client.env.json (or http-client.env.json) is a regular file that is meant to be distributed together with your project.

  • The rest-client.private.env.json (or http-client.private.env.json) is a private file that may contain sensitive information (passwords, tokens, certificates, etc.). This file is added to the VCS ignored files list by default. The variables' values specified in a private file override the ones contained in a regular environment file.

In addition, you can work with variables programmatically in your response handler scripts by means of the client.global.get and client.global.set methods.

Example: Working with environment files

The following sample http-client.env.json environment file defines two environments: development and production.

{ "development": { "host": "localhost", "id-value": 12345, "username": "", "password": "", "my-var": "my-dev-value" }, "production": { "host": "example.com", "id-value": 6789, "username": "", "password": "", "my-var": "my-prod-value" } }

The additional http-client.private.env.json file holds the authorization sensitive data:

{ "development": { "username": "dev-user", "password": "dev-password" }, "production": { "username": "user", "password": "password" } }

The example HTTP request is as follows:

GET http://{{host}}/api/json/get?id={{id-value}}&key={{unresolved_var}} Authorization: Basic {{username}} {{password}} Content-Type: application/json { "key": {{my-var}} }

When you execute the above request, JetBrains Rider provides a choice between the defined execution environments:

run_request_in_env

Depending on your choice, the resulting request will be one of the following:

  • development:

    GET http://localhost/api/json/get?id=12345&key={{unresolved_var}} Authorization: Basic dev-user dev-password Content-Type: application/json { "key": "my-dev-value" }

  • production:

    GET http://example.com/api/json/get?id=6789&key={{unresolved_var}} Authorization: Basic user password Content-Type: application/json { "key": "my-prod-value" }

Since the {{unresolved-var}} variable is not defined in the environment file, JetBrains Rider will send the {{unresolved-var}} text as part of the request in both cases.

Using response handler scripts

Response handler scripts let you programmatically 'react' to a received HTTP response. This enables automated processing of the received data as well as validating it against the conditions you specify. Response handler scripts are provided as part of the request within the HTTP request file and are executed as soon as a response is received. To view the response handling examples, open the auth-requests or test-responses requests collections.

You can insert a response handler script into your request either in-place or by referring to an external file.

To insert the script in place, prepend it with > and enclose it in {% %}:

GET host/api/test > {% // Response Handler Script ... %}

To insert the script by referring to an external file, prepend it with >:

GET host/api/test > scripts/my-script.js

Response handler scripts are written in JavaScript, with coding assistance and documentation handled by the bundled HTTP Response Handler library. For in-place scripts, this functionality is enabled automatically.

To enable HTTP Response Handler coding assistance in a JavaScript file

  1. Open the file in the editor.

  2. In the context menu, choose Use JavaScript Library | HTTP Response Handler.

The HTTP Response Handler library exposes two objects to be used for composing response handler scripts:

  • client stores the session metadata, which can be modified inside the script. The client's state is preserved until you close JetBrains Rider. Every variable saved in client.global as variable_name is accessible to subsequent HTTP requests as {{variable_name}}.

  • response holds information about the received response: its content type, status, response body, and so on.

Response handler scripts can include tests, which allows you to use the HTTP Client as a testing framework. To create a test, invoke the client.test(testName, function) method. Inside the test, you can assert a condition by invoking the client.assert(condition, message) method, for example:

GET https://httpbin.org/status/200 > {% client.test("Request executed successfully", function() { client.assert(response.status === 200, "Response status is not 200"); }); %}

Example: Working with environment variables programmatically

The following example demonstrates capturing a certain value from the received response into an environment variable and then using it in a subsequent request.

The first request involves a response handler script, which saves an authentication token from the received response into the auth_token variable. To achieve this, the client.global.set(VariableName, VariableValue) construction is used:

POST https://httpbin.org/post Content-Type: application/json { "token": "my-secret-token" } //Saving a variable > {% client.global.set("auth_token", response.body.json.token); %}

After the request is executed, the auth_token variable can be accessed from both subsequent requests as {{auth_token}} and response handler scripts by means of the client.global.get("auth_token") construction.

//Accessing a variable GET https://httpbin.org/headers Authorization: Bearer {{auth_token}}

Executing an HTTP request

  1. If you are going to test your own web service, make sure it is deployed and running.

  2. Do any of the following:
    • Click the Run icon The Run button in the left gutter of the editor next to the request you want to run. In the pop-up menu, select Run <request name>.

    • Place the caret at the request you want to execute, press Alt+Enter and select the Run <request name> intention action.

To open a request in the browser

You can open an HTTP request in the browser specified on the Web Browsers page of the Settings/Preferences dialog. This can be your system default browser, or the one of your choice.

  • Do any of the following:
    • Place the caret at the request's first line and choose View | Jump to Source on the main menu, or press F12 or F4.

    • Ctrl+Click (for Windows and Linux) or ⌘+Click (for macOS) the request line:

      open_request_in_browser

Viewing responses from web services

When you execute an HTTP request, JetBrains Rider automatically saves the response into a separate file under the .idea/httpRequests/ directory. You can view the 50 most recently stored responses and navigate to the corresponding files using the requests history. If the request was executed from a scratch file, the link to its response output is also added below the original request:

response_results

To view a received response

  1. Switch to the Run window, which opens automatically as soon as a response is received.

  2. By default, the server response is shown in the format specified in the request header via the content-type field. To have the response converted into another format, use the View as HTML The View as HTML button, View as XML The View as XML button, or View as JSON The View as JSON button buttons.

  3. The results of the tests executed as part of a response handler script, if any, are displayed on the Tests tab of the Run tool window.

    The Tests tab of the Run tool window

To open a response file in the editor

  • Place the caret at the link to the response you want to open, and choose View | Jump to Source on the main menu, or press F12 or F4.

  • Ctrl+Click (for Windows and Linux) or ⌘+Click (for macOS) the response line:

    open_response

To compare responses in a scratch file

When a request is executed from a scratch file, the link to the response output file is added below the original request.

  • Do any of the following:
    • Place the caret at the link to the response file. Press Alt+Enter and select the Compare with <response name> intention action.

    • Click the ps_compare_responses_icon icon in the left gutter and select Compare with <response name> from the pop-up menu:

      compare_responses_menu

To compare responses in the requests history

When a request is executed from a physical file, the link to the response output is added to the requests history.

  1. Place the caret at the link to the response file. Choose View | Jump to Source on the main menu, or press F12 or F4 to open this file in a new editor tab.

  2. Choose View | Compare with... on the main menu, or press Ctrl+D. JetBrains Rider will prompt you to open a response file from the httpRequests folder.

  3. Select the response file you would like to compare the current file with and click Open.

The two response files will be opened in the Differences viewer allowing you to compare their contents:

compare_responses_diff

Viewing requests history

JetBrains Rider automatically saves the 50 recently executed requests into the http-requests-log.http file, which is stored on the project level under the .idea/httpRequests/ directory. Using the requests history, you can quickly navigate to a particular response as well as re-run any request. If a request is re-run from the requests history, its execution information and the link to the response output will be added to the top of the requests history file.

ps_requests_history

To open the requests history

  • Click Show HTTP Requests History in the top-right corner of the editor or choose Tools | HTTP Client | Show HTTP Requests History on the main menu.

Configuring Proxy settings

  1. In the Settings/Preferences dialog (Ctrl+Alt+S), choose System Settings under Appearance & Behavior, then choose HTTP Proxy.

  2. In the Proxy dialog that opens, select Manual proxy configuration and specify the following:
    • Enter the proxy host name and port number in the Host name and Port number fields.

    • To enable authorization, select the Proxy authentication checkbox and type the user name and password in the corresponding fields.

Last modified: 13 November 2018