RubyMine 2017.3 Help

REST Client in RubyMine Code Editor

Basics

When testing a RESTful Web Service, you can create, edit, and execute HTTP Requests directly in the RubyMine code editor, as an alternative to using the REST Client Tool Window.

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

Testing RESTful Web Services is supported via the REST Client bundled plugin. The plugin is activated by default. If the plugin is disabled, enable it on the Plugins page as described in Enabling and Disabling Plugins.

Support inside the code editor

Support for HTTP files inside the RubyMine code editor includes the following:

Working with HTTP requests

Creating an HTTP request

To create an HTTP request, you need to create a new scratch or physical file and compose the request in the code editor.

Differentiating between the HTTP request file types

When working with HTTP requests in the code editor, you can compose your requests using either a scratch file or a physical file. RubyMine offers different behavior depending on the file type.

Scratches
Scratches, or scratch files, are used during the development process. A scratch file is not stored inside a project, so RubyMine can modify it and add additional information about the request.

If a request is executed from a scratch file, the link to the response output file will be added beneath this request as well as to the top of the requests history file.

Physical files
Physical files are used for documenting, testing and validating of HTTP requests. A physical file is stored inside your project, and RubyMine will not modify it.

If a request is executed from a physical file, this file will not be modified. The information about the executed request with the link to the response output file will be added to the top of the requests history file.

Creating an HTTP request file

Depending on your needs, do one of the following:

Composing an HTTP request

To compose an HTTP request, type it directly in the created .http or .rest file.

You can find the full HTTP request format description at RFC 7230. In a nutshell, HTTP requests are structured following this general pattern:

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

RubyMine enhances the HTTP request format with several useful accommodations. Let us examine them via several example HTTP files.

We'll start with a very simple request. When we omit the request method, GET is automatically used. As a result, a request can be as short as the Request-URI itself. Note that we've included a comment in the request by starting a line with //. You can also use # to start a comment line.

// A basic request http://example.com/a/

Let us create the second request. It's not necessary to create a separate file for it. Instead, we can type ### to mark the end of the previous request:

http://example.com/a/ ### GET http://example.com:8080/api/html/get?id=123&value=content

Note that the request query string is rather long, and it may be more convenient to present it on several lines. We can do it by indenting all query string lines but the first one:

GET http://example.com:8080 /api /html /get ?id=123 &value=content

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 RubyMine, then the corresponding language fragment will be auto-injected for the request's message body.
  • To read the request body from a file, simply 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 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 parameterize its components by 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 environments variables in your project holding the desired hosts definitions. When executing a request, RubyMine will allow you to choose between the defined environments, in our case, the host to send the request to:

run_request_in_env

Environment variables are defined in the rest-client.env.json environment files, which must be stored inside the project.

A variable can hold the values for host, port, path, query parameter or value, and header value. The name of a variable can only contain letters, digits, the underscore symbol (_), or the hyphen symbol (-).

Let us consider an example environment file, in which we have defined two environments: development and production.

{ "development": { "host": "localhost", "id-value": 12345 }, "production": { "host": "example.com", "id-value": 6789 } }

The example HTTP request is as follows:

GET http://{{host}}/api/json/get?id={{id-value}}&key={{unresolved_var}}

When you execute the above request, RubyMine will propose to choose between the defined execution environments:

run_request_in_env

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

  • Development:
    GET http://localhost/api/json/get?id=12345&key={{unresolved_var}}
  • Production:
    GET http://example.com/api/json/get?id=6789&key={{unresolved_var}}

Notice that the {{unresolved-var}} variable is not defined in the environment file. RubyMine in this case will simply send the {{unresolved-var}} text as part of the request in both cases.

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 run_icon in the left gutter of the editor next to the request you want to run. On 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.

After the request is executed, you can navigate to the received response.

Opening a request in the browser

You can open an HTTP request in the browser specified in the Web Browsers section of the RubyMine settings. This can be your system default browser, or the one of your choice.

To open an HTTP request in the browser, 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 Ctrl+B or F4.
  • Ctrl+Click (for Windows and Linux) or ⌘+Click (for macOS) the request line:
    open_request_in_browser

Moving an HTTP request

Using the Move refactoring, you can move your HTTP requests from scratches to physical files as well as between physical files.

  1. Select the request to be moved and do one of the following:
    • On the main menu, or on the context menu, choose Refactor | Move.
    • Press F6.
  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.

Working with responses

When you run a request, RubyMine 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 beneath the original request:

response_results

Opening a response

To open a particular response in a new editor tab, do any of the following:

  • 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 Ctrl+B or F4.
  • Ctrl+Click (for Windows and Linux) or ⌘+Click (for macOS) the response line:
    open_response

Comparing responses

When a request is executed from a scratch file, the link to the response output file is added beneath the original request. To compare the request execution results in a scratch file, 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

When a request is executed from a physical file, the link to the response output is added to the requests history. To compare the execution results in the requests history, do the following:

  1. Place the caret at the link to the response file. Choose View | Jump to Source on the main menu, or press Ctrl+B or F4 to open this file in a new editor tab.
  2. Choose View | Compare with... on the main menu, or press Ctrl+D. RubyMine 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

RubyMine 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:

ps_requests_history

Opening the requests history

To open the requests history, click the Show HTTP Requests History icon show http requests history button in the top-right corner of the editor or choose Tools | Show HTTP Requests History on the main menu.

Last modified: 29 November 2017

See Also