REST Client in IntelliJ IDEA Code Editor
When testing a RESTful Web Service, you can create, edit, and execute HTTP Requests directly in the IntelliJ IDEA 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.
Support for HTTP files inside the IntelliJ IDEA code editor includes the following features:
- Code highlighting
- Code completion for method types and header fields
- Viewing structure of HTTP requests
- Language injections inside the request message body
- Move refactorings
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 IntelliJ IDEA 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 IntelliJ IDEA 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 new physical HTTP requests file, on the File menu, point to New, and then click HTTP Request.
Composing an HTTP request
You can type HTTP requests directly in the created HTTP request file.
You can find the full HTTP request format description in RFC 7230. The general syntax for HTTP requests is the following:
Method Request-URI HTTP-Version
Header-field: Header-value
Request-Body
IntelliJ IDEA enhances the HTTP request format with several useful accommodations, as demonstrated by the following examples:
-
You can omit the request method and specify only the URI to use
GET
by default:// 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 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 IntelliJ IDEA, then the corresponding language fragment will be auto-injected into the HTTP request message body. - 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
- If you set the
-
You can execute HTTP requests with the
multipart/form-data
content type. To send a file as part of themultipart/form-data
message, include thefilename
parameter in theContent-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 executing the request, IntelliJ IDEA will provide a choice of defined environments, in our case, the host to send the request to:
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 the variable can only contain letters, digits, the underscore symbol (_
), or the hyphen symbol (-
).
The following sample environment file defines 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, IntelliJ IDEA provides a choice between the defined execution environments:
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}}
The {{unresolved-var}}
variable is not defined in the environment file, so IntelliJ IDEA sends the {{unresolved-var}}
text as part of the request in both cases.
Executing an HTTP request
- If you are going to test your own web service, make sure it is deployed and running.
- Do any of the following:
- Click the 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 IntelliJ IDEA 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 on the main menu, or press Ctrl+B or F4.
- Ctrl+Click (for Windows and Linux) or ⌘+Click (for macOS) the request line:
Moving an HTTP request
You can use the Move refactoring to move your HTTP requests from scratches to physical files, as well as between physical files.
- Select the request to be moved and do one of the following:
- On the main menu, or on the context menu, choose .
- Press F6.
- In the dialog box that opens, click 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.
Opening a response
When you execute an HTTP request, IntelliJ IDEA 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:
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 on the main menu, or press Ctrl+B or F4.
- Ctrl+Click (for Windows and Linux) or ⌘+Click (for macOS) the response line:
Comparing responses
When a request is executed from a scratch file, the link to the response output file is added below 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 icon in the left gutter and select Compare with <response name> from the pop-up 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:
- Place the caret at the link to the response file. Choose on the main menu, or press Ctrl+B or F4 to open this file in a new editor tab.
- Choose
httpRequests
folder. on the main menu, or press Ctrl+D. IntelliJ IDEA will prompt you to open a response file from the - 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:
Viewing requests history
IntelliJ IDEA 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.
To open the requests history, click the Show HTTP Requests History button in the top-right corner of the editor or choose on the main menu.