Secure outbound requests
Call an external HTTPS endpoint and process its streamed response.
Node.js · Module
node:https
node:https provides Node.js client and server APIs for HTTP over TLS/SSL. It supports secure requests, HTTPS servers, connection agents, and TLS-specific configuration.
How it works
The node:https module supplies HTTPS client and server APIs. Use https.get() for a GET request or https.request() for fuller control, including TLS settings; requests return writable HTTP client request streams, while servers listen for encrypted connections.
Syntax
import * as https from 'node:https';
https.get(url[, options][, callback]);
https.request(options[, callback]);
https.createServer([options][, requestListener]);Parameters
| Name | Type | Description |
|---|---|---|
url/options | string | URL | Object | Request target or request configuration; https.get() accepts a URL, string, or options object, while https.request() accepts options. |
callback | Function | Function invoked with the incoming response or request event, depending on the API. |
Returns
https.get() returns an http.ClientRequest; https.request() returns an http.ClientRequest; https.createServer() returns an HTTPS server.
Key points
- This module provides HTTP communication protected by TLS/SSL.
- HTTPS functionality is exposed independently from the HTTP module.
- Use
https.get()when a secure GET request is sufficient. - Use
https.request()when you need a configurable secure client request. - A request body can be sent through the returned client-request stream.
- HTTPS servers accept encrypted incoming connections after they start listening.
Common mistakes
- A build without
node:cryptosupport cannot import or require this module successfully. - String request targets are converted into URL objects automatically, which affects how they are interpreted.
- TLS-related options are accepted, but unsafe certificate-validation changes should be considered carefully.
Example: Fetch a page over HTTPS
import https from 'node:https';
https.get('https://example.com', (response) => {
let body = '';
response.setEncoding('utf8');
response.on('data', (chunk) => { body += chunk; });
response.on('end', () => console.log(response.statusCode, body.length));
}).on('error', console.error);Performs a secure GET request, collects the streamed response body, and reports the status code and size.
When to use it
TLS-enabled servers
Expose an application endpoint with encrypted transport.
Agent and connection management
Reuse or customize secure client connections.
Interview questions
QHow does https.get() differ from https.request()?
https.get() is the HTTPS counterpart of http.get(). It accepts a URL or options, sets the request method to GET, and returns an HTTP client request whose response arrives through events.
Follow-up: How would you configure mutual TLS? Supply appropriate TLS options such as key, cert, and ca through the request options.
QWhat does https.request() return?
https.request() makes a request to a secure web server and returns an http.ClientRequest. The returned request is a writable stream, so request data can be written before ending it.
Follow-up: What if the request must reuse or customize connections? Configure an HTTPS agent; its createConnection() method can be overridden for TLS connection customization.
QWhat is the role of https.createServer()?
https.createServer() creates a server for encrypted connections. Its listening behavior follows net.Server.listen(), while TLS credentials and other server options configure the secure transport.
Follow-up: What should be checked when a client rejects the server certificate? Verify the certificate chain, hostname, trust configuration, and relevant TLS options rather than disabling validation by default.
Related
https.Agenthttps.createServer()https.get()https.globalAgenthttps.request()http.ClientRequesttls.connect()