HTTP Client
Available only in PyCharm Professional: download to try or compare editions
With the HTTP Client plugin, you can create, edit, and execute HTTP requests directly in the PyCharm code editor.
![https://resources.jetbrains.com/help/img/idea/2023.2/basic_request.png](https://resources.jetbrains.com/help/img/idea/2023.2/basic_request.png)
There are two main use cases when you need to compose and run HTTP requests:
When you are developing a RESTful web service and want to make sure it works as expected, is accessible in compliance with the specification, and responds correctly.
When you are developing an application that addresses a RESTful web service. In this case, it is helpful to investigate the access to the service and the required input data before you start the development. During development, you may also call this web service from outside your application. This may help locate errors when your application results in unexpected output while no logical errors are detected in your code, and you suspect that the bottleneck is the interaction with the web service.
HTTP requests are stored in .http and .rest files and are marked with the icon.
Support for HTTP files includes the following features:
Code completion for hosts, method types, header fields, and endpoints defined via OpenAPI
Code folding for requests, their parts, and response handler scripts
Reformat requests according to your HTTP Request code style.
Inline documentation for request header fields and doc tags
Viewing a structure of HTTP requests
Language injections in Web languages inside the request message body
If necessary, before you begin, configure the Proxy settings on the HTTP Proxy page of the Settings dialog (CtrlAlt0S).
You can work with HTTP requests either from scratch files or from physical files of the HTTP Request type. Each file can contain multiple requests, and you can create as many files as needed.
Scratch files can be used to test HTTP requests during development. Scratch files are not stored inside a project, so PyCharm can modify them 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.
Press CtrlAltShiftInsert and select HTTP Request.
Physical files can be used for documenting, testing, and validating HTTP requests. Physical files are stored inside your project, and PyCharm will not modify them. 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.
In the File menu, point to New, and then click HTTP Request.
You can use the Move refactoring F6 to move HTTP requests from scratches to physical files, as well as between physical files.
In the editor, place the caret at the request to be moved and do one of the following:
From the main menu or the context menu, select Refactor | Move.
Press AltEnter and select the Move HTTP Requests intention action.
Press F6.
In the Move HTTP Requests dialog that opens, do the following:
In the Path field, choose one of the existing .http files from the list or click
to locate the file.
You can also type the full path to the file manually. If you specify the name of a non-existing file, a new file with the provided name will be created automatically.
In the Requests list, select the checkboxes next to the requests you want to move.
PyCharm uses the HTTP request in Editor format, which provides a simple way to create, execute, and store information about HTTP requests. You can type them directly in the created HTTP request files using the following general syntax:
###
Method Request-URI HTTP-Version
Header-field: Header-value
Request-Body
After the ###
separator, you can enter any comments preceded by #
or //
.
tip
To quickly find your request in run/debug configurations, Search Everywhere, and Run Anything, you can give it a name.
note
You can use the Editor | Color Scheme | HTTP Request settings to customize colors and style for highlighting request syntax (name, comments, parameters, headers, and so on).
To speed up composing HTTP requests, you can:
Click Tools | HTTP Client | Create Request in HTTP Client. If a request file is opened in the editor, this will add a request template to the opened file. Otherwise, this will create a new .http scratch file.
Click
on top of the request's editor panel. In the popup menu, choose the type of the request to add.
Alternatively, use live templates. In the editor, you can press Ctrl0J to view the list of available templates. For example, gtr expands to a simple GET request; mptr expands to a multipart/form-data
POST request.
![https://resources.jetbrains.com/help/img/idea/2023.2/expand_post_template.png](https://resources.jetbrains.com/help/img/idea/2023.2/expand_post_template.png)
To get an overview of the HTTP Client possibilities, you can explore the HTTP Requests Collection, which is a handful selection of composed requests.
Click the Examples shortcut link on top of the request's editor panel.
In the popup menu, choose the HTTP Requests collection you wish to open:
note
See Exploring the HTTP request syntax for the syntax and capabilities overview, and HTTP request in Editor specification for the full format description.
If you are working with cURL requests, you can convert between cURL requests and the HTTP request in Editor format.
Paste the cURL request into an HTTP request file. PyCharm will convert it to the HTTP request format and leave the original cURL request commented out for later reference.
Alternatively, click
on top of the HTTP request editor panel and select Convert cURL to HTTP Request.
In the Convert cURL to HTTP Request dialog, type or paste the cURL request that you want to convert.
Consider the following example cURL request:
curl 'http://httpbin.org/' -H 'Connection: keep-alive' -H 'Accept: text/html' -H 'Accept-Encoding: gzip, deflate' -H 'Accept-Language: en-US,en;q=0.9,es;q=0.8'
PyCharm will convert it to the following:
# curl 'http://httpbin.org/' -H 'Connection: keep-alive' -H 'Accept: text/html' -H 'Accept-Encoding: gzip, deflate' -H 'Accept-Language: en-US,en;q=0.9,es;q=0.8'
GET http://httpbin.org/
Connection: keep-alive
Accept: text/html
Accept-Encoding: gzip, deflate
Accept-Language: en-US,en;q=0.9,es;q=0.8
###
The converter supports the following cURL options:
Option | Description |
---|---|
The request method to use. | |
The request header to include in the request. | |
The user's credentials to be provided with the request, and the authorization method to use. | |
The data to be sent in a POST request. | |
The multipart/form-data message to be sent in a POST request. | |
The URL to fetch (mostly used when specifying URLs in a config file). | |
Defines whether the HTTP response headers are included in the output. | |
Enables the verbose operating mode. | |
Enables resending the request in case the requested page has moved to a different location. |
Place the caret at the HTTP request that you want to convert to cURL format.
Click AltEnter and select Convert to cURL and copy to clipboard.
Alternatively, you can click the Convert shortcut link on top of the HTTP request editor panel and select Convert HTTP Request Under Caret to cURL and Copy.
This will generate a cURL request based on the HTTP request and copy it to the clipboard.
You can quickly generate an HTTP request if you have a URL starting with http
or https
in your code string literals or in JSON, YAML, TOML, and Properties files.
Click a URL and press AltEnter.
In the context menu that opens, click Generate request in HTTP Client.
This will create a new GET HTTP request to the specified URL in the generated-requests.http scratch file.
![Generate request in HTTP Client Generate request in HTTP Client](https://resources.jetbrains.com/help/img/idea/2023.2/http_generate_from_context.png)
With response handler scripts, you can programmatically react to a received HTTP response. By using these scripts, you can automatically process the received data as well as validate it against the conditions that you specify. Response handler scripts are provided as a 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 Requests with Authorization or Requests with Tests and Scripts requests collections.
With pre-request scripts, you can set variables used in HTTP requests.
You can insert a response handler script into your request 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 from an external file, prepend it with
>
:GET host/api/test > scripts/my-script.js
If there is any output from the response handler script (errors or output from client.log), it is shown in the Response Handler tab of the Services tool window when you run the request.
You can insert a pre-request script into your request in-place or by referring to an external file.
To insert the script in-place, prepend it with
<
and enclose it in{% %}
:< {% request.variables.set("petName", "Bella") %} POST https://example.org/pets/{{petName}}
To insert the script from an external file, prepend it with
<
:< scripts/my-script.js POST https://example.org/pets/{{petName}}
If there is any output from the pre-request script (errors or output from client.log), it is shown in the Pre-request Handler tab of the Services tool window when you run the request.
Sometimes, you may need to use specific functionalities, such as variables or functions, from external files. For this, in pre-request and response handler scripts, you can use the regular ES6 import feature to access variables and functions defined in local JavaScript files.
Export the needed values from a JavaScript file. The HTTP Client supports
export
statements in the following formats:export let name1, name2/*, … */; // also var export const name1 = 1, name2 = 2/*, … */; // also var, let export function functionName() { /* … */ } export { name1, /* …, */ nameN }; export { variable1 as name1, variable2 as name2, /* …, */ nameN }; export default expression; export default function functionName() { /* … */ } export default function () { /* … */ }
Import the needed values into your response handler or pre-request script. The HTTP Client supports
import
statements in the following formats:import defaultExport from "module-name"; import * as name from "module-name"; import { export1 } from "module-name"; import { export1 as alias1 } from "module-name"; import { export1, export2 } from "module-name"; import { export1, export2 as alias2, /* … */ } from "module-name"; import defaultExport, { export1, /* … */ } from "module-name"; import defaultExport, * as name from "module-name"; import "module-name"; // side effect import
note
If you want to run some tests from an external file and do not need to import anything from them, you can use side effect import in your response handler script, for example
import 'test-scripts/mytests'
. This can be useful if you have common tests and want to reuse them in multiple requests while also keeping the ability to write (or import) individual tests for some requests.
Response handler scripts and pre-request scripts are written in JavaScript ECMAScript 6, with coding assistance and documentation handled by the bundled HTTP Pre-Request and Response Handler
library. For in-place scripts, this functionality is enabled automatically. For external scripts, you need to enable it manually.
Press CtrlShift0A (Find Action).
Type Use JavaScript Library, click the corresponding action, and, in the context menu that opens, select HTTP Pre-Request and Response Handler.
The HTTP Response Handler
library exposes two objects to be used for composing response handler scripts:
The
client
object stores the session metadata, which can be modified inside the script. Theclient
state is preserved until you close PyCharm. Every variable saved inclient.global
asvariable_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.
To open the HTTP Response Handler library in the editor, place the caret at the library object and press Ctrl0B.
Response handler scripts can include tests, which lets you 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");
});
%}
If you are going to test your own web service, make sure it is deployed and running.
If you have environments defined, select an environment in the Run with list on top of the request's editor panel.
In the gutter, click
next to the request.
If you have multiple HTTP requests defined in an .http file, you can run all of them sequentially. To do this, click on top of the request's editor panel.
When a request is executed, PyCharm automatically creates a dedicated temporary HTTP Request run/debug configuration for it. You can save it as a permanent run/debug configuration if necessary.
You can open an HTTP request in the browser specified on the Web Browsers and Preview page of the Settings dialog (CtrlAlt0S).
Press AltEnter and select the Open in web browser intention action.
When you execute an HTTP request from the editor, PyCharm automatically creates a temporary run/debug configuration with the request parameters. A temporary run/debug configuration works the same way as a permanent run/debug configuration. You can change its settings using the Run/Debug Configuration dialog and optionally save it as permanent.
Do any of the following:
In the editor, right-click a request and in the context menu, select Modify Run Configuration....
Alternatively, choose Run | Edit Configurations from the main menu, and select the needed run/debug configuration in the HTTP Request list.
Change the needed configuration parameters:
In the Environment list, select an environment that will define the set of environment variables used in the request.
In the File field, provide the path to the HTTP request file. You can type the path manually and use path completion CtrlSpace as you type, or click
and select the required folder in the dialog that opens.
If your request file contains multiple requests, in the Request list, choose the name of the request to execute.
In the Run/Debug Configuration selector, choose Save <configuration name>.
In the Run/Debug Configuration dialog, select the configuration and click
.
In the Run/Debug Configuration selector, select the desired run configuration. Then click
on the main toolbar or press ShiftF10.
Press AltShiftF10, select the desired run configuration from the list, and press Enter.
When you execute an HTTP request, PyCharm automatically saves the response into a separate file under the .idea
![HTTP response HTTP response](https://resources.jetbrains.com/help/img/idea/2023.2/http_response_in_scratch.png)
Switch to the Services tool window, which opens automatically as soon as a response is received.
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, click
and select Text, JSON, XML, or HTML.
If the response contains a binary file, this file is also saved under the .idea
Preview the image the Services tool window:
![HTTP response with an image HTTP response with an image](https://resources.jetbrains.com/help/img/idea/2023.2/http_response_with_image.png)
Preview the PDF file the Services tool window. To disable showing PDF preview in the Services tool window, click and clear the Enable PDF preview inline option.
![HTTP response with a PDF HTTP response with a PDF](https://resources.jetbrains.com/help/img/idea/2023.2/http_response_with_pdf.png)
If the response is an HTML file, you can click Show Preview to preview it in the editor tab using the JCEF-based browser.
![HTTP response with HTML HTTP response with HTML](https://resources.jetbrains.com/help/img/idea/2023.2/http_response_with_html.png)
If you have a response handler script, the results of the tests executed as part of this script are displayed on the Tests tab of the Services tool window. You can click each of the tests to quickly navigate to the test source code in the corresponding response handler script.
![The Tests tab of the Services tool window The Tests tab of the Services tool window](https://resources.jetbrains.com/help/img/idea/2023.2/http-request-failed-tests.png)
If you subscribe to an event stream, PyCharm displays events in the Services tool window. Here, you can also view the status of the client-server connection and terminate it by clicking . Depending on the content type (either
text/event-stream
or application/x-ndjson
), the response will be formatted as plain text or newline-delimited JSON. You can write a response handler script to process each line of the event stream.
![Server-sent events Server-sent events](https://resources.jetbrains.com/help/img/idea/2023.2/http_client_json_event_stream.png)
Redirecting stream events to a file is currently not supported.
Place the caret at the link to the response you want to open.
Choose View | Jump to Source from the main menu, or press Ctrl0B or F4
Alternatively, you can CtrlClick the response line.
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 AltEnter and select the Compare with <response name> intention action.
Click
in the gutter and select Compare with <response name> from the list:
When a request is executed from a physical file, the link to the response output is added to the requests history.
Place the caret at the link to the response file. Choose View | Jump to Source from the main menu, or press Ctrl0B or F4 to open this file in a new editor tab.
Choose View | Compare With from the main menu, or press Ctrl0D. PyCharm will prompt you to open a response file from the httpRequests folder.
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 HTTP responses Compare HTTP responses](https://resources.jetbrains.com/help/img/idea/2023.2/compare_http_responses_diff.png)
PyCharm automatically saves the 50 recently executed requests into the http-requests-log.http file, which is stored on the project level under the .idea
note
To prevent saving a request to the request history, add a comment line with the @no-log tag before the request. This can be helpful in case a request contains some sensitive data, and you don't want to log it.
Click
on top of the request's editor panel.
Select Tools | HTTP Client | Show HTTP Requests History from the main menu.
The HTTP Client can redirect output to a custom file or directory. It supports two operators for force and soft redirects:
The
>>
operator always creates a new file, adding an-n
suffix to a filename if the requested filename already exists.The
>>!
operator rewrites the file if it already exists.
The cookies received through a response are automatically saved into the dedicated http-client.cookies file under the .idea
![the http-cookies file the http-cookies file](https://resources.jetbrains.com/help/img/idea/2023.2/ps_http_cookie.png)
note
You can prevent saving the received cookie to the cookie jar by adding a comment line with the @no-cookie-jar tag before the request.
If you want to set custom cookies in an HTTP request, you can use the Cookie
header. Enter your cookies as a list of name=value
pairs separated by a semicolon, for example:
GET http://localhost:80/api
Cookie: theme=dark; country=France
The HTTP Client supports WebSocket requests. For the HTTP Client to treat your request as a WebSocket request, start it with the WEBSOCKET
keyword followed by a server address. The request has the following structure:
WEBSOCKET ws://localhost:8080/websocket
Content-Type: application-json // Used for content highlighting only
// Request body, for example:
{
"message": "First message sent on connection"
}
=== // message separator
{
"message": "Second message" // will be sent right after the previous one
}
=== wait-for-server // keyword used to wait for the server response
{
"message": "Send this after the server response"
}
note
While the
Content-Type
header is not used in WebSocket connections, you can use it PyCharm WebSocket requests to highlight syntax of transmitted data.
To speed up composing a WebSocket request, you can:
Click
on top of the editor panel of an .http file and select WebSocket Request.
In an .http file, type
wsr
and press Enter to apply the WebSocket live template.
Use the
===
separator to send multiple messages:{ "message": "First message sent on connection" } === // message separator { "message": "Second message" } === { "message": "Third message" }
Before a message, enter
=== wait-for-server
.This will make the HTTP Client wait for the server response before sending the message. You can wait for multiple responses by repeating the
=== wait-for-server
line. For example, the following message will be sent after 3 server responses:=== wait-for-server === wait-for-server === wait-for-server { "message": "This messages is sent after 3 server responses" }
Once you have initiated a connection, you can interact with your server right from the Services tool window. You can send messages and view server responses to each new message.
In the Services tool window, select an opened connection.
In the lower part of the window, under Message to be sent to WebSocket, enter the message content.
To the right of it, select the message format: plain text, JSON, XML, or HTML.
Press CtrlEnter to send the request.
In the upper part of the window, you'll see the server response.
![The Services tool window The Services tool window](https://resources.jetbrains.com/help/img/idea/2023.2/websocket_interactive.png)
PyCharm provides support for sending GraphQL operations in the HTTP request body. You can send them over HTTP or WebSocket.
tip
For the GraphQL language support in the request body (syntax highlighting, quick navigation to schemas, and so on), you can install and enable the GraphQL plugin.
In an .http file, enter the
GRAPHQL
keyword followed by a server address.In the request body, compose your GraphQL operation (query, mutation, or subscription), for example:
### HTTP request with GraphQL query GRAPHQL http://localhost:8080/graphql query { toDos { title, completed, author { username } } }
To speed up composing an HTTP request with a GraphQL query, you can:
Click
on top of the editor panel of an .http file and select GraphQL Query Request.
In an .http file, type
gqlr
and press Enter to apply the GraphQL live template.
In the HTTP request body, you can use GraphQL variables if you want to pass some dynamic data separately from the query string.
After the query part, enter a JSON variables dictionary:
query ($name: String!, $capital: String!) { country(name: $name, capital: $capital) { name capital } } { "name": "France", "capital": "Paris" }
You can also use HTTP Client environment variables as GraphQL variable values. For example, in this JSON,
"{{Author}}"
is an environment variable; its value at runtime depends on the environment that you select while sending the request:{ "author": "{{Author}}" }
note
You can quickly add a variable block to the GraphQL query by pressing AltEnter (Show Context Actions) in the request body and selecting Add GraphQL JSON variables block.
In the Settings dialog (CtrlAlt0S), choose System Settings under Appearance & Behavior, then choose HTTP Proxy.
In the HTTP 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 username and password in the corresponding fields.
If an HTTP server requires SSL/TLS authentication for secure communication, you may need to specify the client certificate before sending an HTTPS request. In the HTTP Client, you can set up the client certificate using the private environment file.
In an .http file, in the Run with list, select Add Environment to Private File….
In the http-client.private.env.json file that opens, add the
SSLConfiguration
object to the needed environment. InclientCertificate
, enter a path to your client certificate. If a certificate key is stored in a separate file, enter its path inclientCertificateKey
. For example:{ "dev": { "MyVar": "SomeValue", "SSLConfiguration": { "clientCertificate": "cert.pem", "clientCertificateKey": "MyFolder/key.pem" } } }
tip
You can specify an absolute path or a path relative to the http-client.private.env.json file. If the environment file is stored in scratches, you can additionally specify a path relative to your project root. Start typing a path to get the code completion popup.
Alternatively, you can describe
clientCertificate
andclientCertificateKey
as objects, which lets you specify the certificate format in addition to the path. For example:{ "dev": { "SSLConfiguration": { "clientCertificate": { "path": "file.crt", "format": "PEM" }, "clientCertificateKey": { "path": "file.key", "format": "DER" } } } }
If you used a passphrase when generating your client certificate, you should provide it to the HTTP Client.
In the http-client.private.env.json file, add
"hasCertificatePassphrase": true
to theSSLConfiguration
object, for example:{ "dev": { "SSLConfiguration": { "clientCertificate": "file.crt", "hasCertificatePassphrase": true } } }
Click
in the gutter or, with the caret placed at
hasCertificatePassphrase
, press AltEnter and select Set value for 'Certificate passphrase'.In the window that opens, enter your certificate passphrase.
![HTTP Client Secured Value window HTTP Client Secured Value window](https://resources.jetbrains.com/help/img/idea/2023.2/http_client_set_passphrase.png)
You can omit the second step if you do not want to enter the passphrase now. In this case, PyCharm will prompt you to enter the passphrase when you execute an HTTPS request.
For development purposes, you may have a host with self-signed or expired certificates. If you trust this host, you can disable verification of its certificate.
In the http-client.private.env.json file, add
verifyHostCertificate": false
to theSSLConfiguration
object. For example:{ "sslTest": { "SSLConfiguration": { "verifyHostCertificate": false } } }
If you run a request with this environment, PyCharm will not verify host certificates.
Thanks for your feedback!