Skip to main content

http.urlencode(dataTable)

Encodes a table of key-value pairs into a single URL-encoded string

Availability

Agent

Parameters

Name Type Description
dataTable Table The key-value pair(s) to be encoded

Returns

String — the URL-encoded data

Description

This method performs URL encoding, as defined in the RFC3986 specification, sections 2.1 to 2.3. The encoded form is often needed when the agent is interacting with web services: for instance, query strings in the URL of an HTTP GET request must be URL-encoded, in case they contain any of the ‘reserved’ characters:

{ " : / ? # @ ! $ & ' ( ) * + , ; = }

The table passed to the method as its parameter should contain key-value pairs, where the keys are strings and the values are either strings, integers or floats — or arrays of strings, integers or floats. Arrays may not be nested: more complex compound data should probably be sent in JSON format instead.

Note null values are currently encoded as follows:

server.log(http.urlencode({ "foo" : null }));

outputs:

foo=%28null%20%3A%20%28nil%29%29

If this is not your desired result, we recommend pre-processing the passed table to remove null values before encoding. For instance:

local d = { "foo" : null, "bar": 2 };

server.log(http.urlencode(d));

foreach(k, v in d) {
    if (v == null) d.rawdelete(k);
}

server.log(http.urlencode(d));

Outputs:

2024-01-12T14:28:24.355 +00:00 [Agent] foo=%28null%20%3A%20%28nil%29%29&bar=2
2024-01-12T14:28:24.355 +00:00 [Agent] bar=2

The corresponding decoding operation is http.urldecode().

Example Code

As an example of how it would be used in practice, here’s some agent code that takes a table of data from an imp and encodes it for sending as if POST-ed by an HTML form.