Exploring the HTTP request syntax

Use comments in HTTP requests

• Within a request, start any line with // or # to make it a comment line.

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

Set names for HTTP requests

To quickly find your request in run/debug configurations, Search Everywhere, and Run Anything, you can give it a name.

• Type a name above the request next to ###, # @name, or # @name =.

  

If a request does not have a name, IntelliJ IDEA will use its position in the request file (such as #1) as the request name. If a request file contains multiple requests with the same name, IntelliJ IDEA will append the request position number to each of the names. This will make each request name unique so that you can easily find the needed one in the Services tool window, run/debug configurations, and so on.

Use short form for GET requests

• For GET requests, you can omit the request method and only specify the URI.

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

  In the Java context, you can use code completion Ctrl+Space to specify URIs based on the defined @Path annotations. Any changes to the @Path annotations in Java code will be reflected in the contents of the suggestion list.

Compose several requests in a single file

1. Mark the end of a request by typing the ### separator below it.

   // A basic request https://example.com/a/ ###

2. Compose another request below the separator.

   // A basic request https://example.com/a/ ### // A second request using the GET method https://example.com:8080/api/html/get?id=123&value=content

Break long requests into several lines

• Indent all query string lines but the first one.

  // Using line breaks with indent GET http://example.com:8080 /api /html /get ?id=123 &value=content

• If the URL is too long because of the query string, you can use the dedicated context action to put each query parameter on a new line. Place the caret at the query string part, press Alt+Enter (Show Context Actions), and select Put query parameters on separate lines.

  GET https://example.com:8080/api/get/html?firstname=John&lastname=Doe&planet=Tatooine&town=Freetown

  GET https://example.com:8080/api/get/html? firstname=John& lastname=Doe& planet=Tatooine& town=Freetown

• Similarly, you can format the body in requests with Content-Type: application/x-www-form-urlencoded. Place the caret at the body, press Alt+Enter (Show Context Actions), and select Put form-urlencoded parameters on separate lines.

  POST https://ijhttp-examples.jetbrains.com/post Content-Type: application/x-www-form-urlencoded key1=value1&key2=value2&key3=value3&key4=value4&key5=value5

  POST https://ijhttp-examples.jetbrains.com/post Content-Type: application/x-www-form-urlencoded key1 = value1 & key2 = value2 & key3 = value3 & key4 = value4 & key5 = value5

  To configure wrapping for the x-www-form-urlencoded body, use Settings | Editor | Code Style | HTTP Request | Wrapping and Braces | Form-urlencoded parameters wrap. To configure spaces before and after = and before &, use Settings | Editor | Code Style | HTTP Request | Spaces.

Access a web service with authentication

• Depending on the web service you are accessing, provide the basic or digest Authorization header.

  // Basic authentication GET http://example.com Authorization: Basic username password ### // Digest authentication GET http://example.com Authorization: Digest username password

Provide the request message body

Inside the request, prepend the request body with a blank line and do one of the following:

• Type the request body in place:

  // The request body is provided in place POST https://example.com:8080/api/html/post HTTP/1.1 Content-Type: application/json Cookie: key=first-value { "key" : "value", "list": [1, 2, 3] }

  If you set the Content-Type header field value to one of the supported languages, 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.

• In the Java context, you can use code completion Ctrl+Space to specify the Accept header field value based on the defined @Produces annotations. Any changes to the @Produces annotations in Java code will be reflected in the contents of the suggestion list.

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

  // The request body is read from a file POST https://example.com:8080/api/html/post Content-Type: application/json < ./input.json

Use multipart/form-data content type

• Set the request's Content-Type to multipart/form-data. To send a file as part of the multipart/form-data message, include the filename parameter in the Content-Disposition header.

  POST https://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--

Disable following redirects

When an HTTP request is redirected (a 3xx status code is received), the redirected page response is returned. In the Services tool window, you can view the redirected page response as well as all redirections that happened during the request.

You may want to disable following redirects. In this case, the actual redirect response header (such as 301 or 302) is returned.

• Before the request, add a comment line with the @no-redirect tag.

  // @no-redirect example.com/status/301

If you already have a redirected request, you can click Disable next to the Redirections list in the Services tool window. This will add the @no-redirect tag to the initial request.

Disable saving requests to requests history

If necessary, you can prevent saving a request to the requests history. This can be helpful in case a request contains some sensitive data, and you don't want to log it.

• Before the request, add a comment line with the @no-log tag.

  // @no-log GET example.com/api

Disable saving received cookies to the cookies jar

If necessary, you can prevent saving the received cookie to the cookies jar. This way you will avoid removing the unwanted cookies from the http-client.cookies file manually.

• Before the request, add a comment line with the @no-cookie-jar tag.

  // @no-cookie-jar GET example.com/api

Disabling encoding

By default, the HTTP client encodes the request parameters and body into an ASCII format. For example, a slash character in your request parameter will be sent as %2F. You can disable encoding to send the request as it is.

• Before the request, add a comment line with the @no-auto-encoding tag.

  When the tag is used, the request parameters and body are not encoded:

  # @no-auto-encoding GET https://examples.com/api? name=@#$somebody& qwerty=%40%23%24

  The resulting request will be sent unchanged:

  https://examples.com/api?name=@#$somebody&qwerty=%40%23%24

  Encoding is enabled by default when the tag is not used.

  ### Default behavior GET https://examples.com/api? name=@#$somebody& qwerty=%40%23%24

  In this request, parameters will be encoded:

  https://examples.com/api?name=%40%23%24somebody&qwerty=%40%23%24

Customize HTTP request timeouts

The HTTP Client has a timeout of 60 seconds for establishing a connection with a server, and a separate 60 seconds timeout for awaiting new packets in ongoing connections. You can customize both of these timeouts.

• To set a timeout for new packets in established connections, add a comment line with the @timeout tag before the request.

  # @timeout 600 GET example.com/api

• To set a connection timeout, add a comment line with the @connection-timeout tag before the request.

  // @connection-timeout 2 m GET example.com/api

By default, the timeout values are in seconds, but you can add an explicit unit of time after the value: ms for milliseconds, s for seconds, m for minutes, for example 100 ms or 5 m.