HttpSession

HTTP client session for executing multiple requests with shared settings, reused connections, and a cookie jar. Settings and authentication set on the session are defaults for all requests executed within it; an HttpRequest executed with execute() can override any of them. Session headers and request headers are merged, with request headers taking precedence.

The same restrictions apply as for HttpRequest: HTTP requests from scripts must be enabled by server configuration variable NXSL.HttpRequests.Enabled, and a script executed on behalf of a user requires the "Execute HTTP requests from scripts" system access right.

Instance attributes

All attributes except cookies are writable and have the same meaning as on HttpRequest, but act as defaults for every request executed within the session. Settings attributes read as null until set; headers reads as an empty hash map. Setting a settings attribute to null resets it to "not set", in which case the server default is used.

cookies: HashMap: Cookies currently stored in the session’s cookie jar, as hash map of cookie name to value. Read-only.

followRedirects: bool: Follow HTTP redirects. Default is true.

headers: HashMap: Session headers as hash map of header name to value, added to all requests executed within the session. Assigning a hash map replaces all session headers (assigning null removes all of them); use setHeader() to change a single header. Header names and values are validated, invalid entries and entries with null value are ignored.

maxResponseSize: int64: Maximum accepted response body size in bytes. Default and upper limit is 16 MB. If the response is larger, the request fails with an error.

proxy: String: Proxy server URL, or null to connect directly.

timeout: int: Request timeout in seconds.

userAgent: String: Value of the User-Agent header. Default is NetXMS Server/<version>.

verifyHost: bool: Verify that server certificate matches the host name in the URL. Default is true.

verifyPeer: bool: Verify server certificate against trusted certificate authorities. Default is true.

Instance methods

Authentication and header methods behave the same as on HttpRequest, but apply to every request executed within the session unless the request overrides them.

clearAuth(): void: Reset session authentication to "not set". Requests executed within the session use no authentication unless they set their own.

clearCookies(): void: Remove all cookies from the session’s cookie jar.

close(): void: Close all connections and discard cookies. The session object can be used again afterwards as a new session.

delete(url) ⇒ HttpResponse

Execute DELETE request within the session.

Table 1. Parameters
url	String	Request URL.

Return

HttpResponse object.

execute(request) ⇒ HttpResponse

Execute prepared HttpRequest within the session. Settings not set on the request are taken from the session.

Table 2. Parameters
request	HttpRequest	Request to execute.

Return

HttpResponse object.

get(url) ⇒ HttpResponse

Execute GET request within the session.

Table 3. Parameters
url	String	Request URL.

Return

HttpResponse object.

head(url) ⇒ HttpResponse

Execute HEAD request within the session.

Table 4. Parameters
url	String	Request URL.

Return

HttpResponse object.

patch(url, body) ⇒ HttpResponse

Execute PATCH request within the session.

Table 5. Parameters
url	String	Request URL.
body	String, JsonObject, JsonArray, array, or hash map	Request body. See HttpRequest::body for serialization rules.

Return

HttpResponse object.

post(url, body) ⇒ HttpResponse

Execute POST request within the session.

Table 6. Parameters
url	String	Request URL.
body	String, JsonObject, JsonArray, array, or hash map	Request body. See HttpRequest::body for serialization rules.

Return

HttpResponse object.

put(url, body) ⇒ HttpResponse

Execute PUT request within the session.

Table 7. Parameters
url	String	Request URL.
body	String, JsonObject, JsonArray, array, or hash map	Request body. See HttpRequest::body for serialization rules.

Return

HttpResponse object.

removeHeader(name): void

Remove session header. The header is no longer added to requests executed within the session.

Table 8. Parameters
name	String	Header name.

setAuth(type, login, password): bool

Set session authentication method and credentials, used by all requests executed within the session that do not set their own authentication.

Table 9. Parameters
type	String	Authentication type: `"none"`, `"basic"`, `"digest"`, `"ntlm"`, or `"bearer"` (case-insensitive).
login	String	User name. Optional, ignored for `bearer`.
password	String	Password, or bearer token for `bearer` type. Optional.

Return

true on success, false if authentication type is not recognized.

setBasicAuth(login, password): void

Set HTTP basic authentication credentials for the session.

Table 10. Parameters
login	String	User name.
password	String	Password.

setBearerAuth(token): void

Set bearer token authentication for the session. The token is not sent to a different host if a request is redirected.

Table 11. Parameters
token	String	Bearer token.

setHeader(name, value): bool

Set session header, added to all requests executed within the session. Header names are matched case-insensitively. A request header with the same name takes precedence.

Table 12. Parameters
name	String	Header name.
value	String	Header value, or `null` to remove the header.

Return

true on success, false if header name or value contains characters not allowed in HTTP headers.

Constructors

HttpSession(): Creates new HTTP session.

Return

HttpSession object, or null if HTTP requests from scripts are disabled or the caller has no access right.

// Log in with a form, then use the session cookie for API calls
session = new HttpSession();
session.timeout = 15;
session.setHeader("Accept", "application/json");

login = session.post("https://portal.example.com/api/login",
   { "user": "monitor", "password": GetConfigurationVariable("Portal.Password") });
if (!login.success)
   return "Login failed: " .. login.statusCode;

status = session.get("https://portal.example.com/api/status");
value = status.json?.get("queueLength");
session.close();
return value;