HTTP Request Parameters

An HTTP request URL is a resource locator used to request data from a specific resource on the web. This URL is composed of several parts, including the scheme (HTTP or HTTPS), host (domain name or IP address), port, path, query string, and fragment.

The path part of the URL indicates the specific resource in the host that the client wants to access. For example, in the URL http://www.example.com/articles, /articles is the path. It is used to specify and categorize resources in the server.

The query part of the URL, on the other hand, is optional and is used to send additional data to the server. It starts with a question mark (?) and includes a series of parameters separated by ampersands (&). Each parameter is a key-value pair. For example, in the URL http://www.example.com/articles?year=2021&author=John, year=2021 and author=John are the parameters. These parameters are used to filter, sort, or provide specific instructions to the server.

Note

The HTTP connector only supports absolute URLs, which means you must always include the scheme and domain.

Parameter placeholders

By default, any values coming to the params port will be converted to URL query parameters and appended to the request URL provided on the url port. However, you can also specify parameter placeholders in the URL that will be replaced with the corresponding values from the params port. To enable this, switch the "Path parameter processing" setting to "Path parameters" mode.

The HTTP connector supports parameter placeholders in both the query and path parts of the URL. Placeholders are strings enclosed in curly brackets {}. For example, in the URL https://example.com/book/{author}/{title}/?page={p}, {author}, {title}, and {p} are parameter placeholders or simply request parameters (not to be confused with the query parameters).

In other parts of the URL (scheme, domain), parameter placeholders will be URL-encoded. For example, a parameter placed in the host part https://{param} will be translated to https://%7Bparam%7D/.

By default, parameters defined in the URL placeholders are considered mandatory unless you specify the * (zero or more) quantifier. If a value for a mandatory parameter is missing on the params port, the connector will fail and throw an exception.

Parameter values

The params port accepts input parameter values as a set of key-value string pairs. You can send these as an array or as an object, which will be converted into an array of arrays internally:

// input **params** array
[
  ["param1", "foo"],
  ["param2", "42"]
]

// input **params** object
{
  "param1": "foo",
  "param2": "42",
  "param3": [123, 456, 789]
}

Note

Using an Object as params input does not guarantee the order of query arguments in the result URL.

Examples

Here are some examples of how to use parameter placeholders:

Single value path placeholder:

URL	https://en.wikipedia.org/wiki/{article}
Params	{"article": "Kelp", "page": 11}
Result	https://en.wikipedia.org/wiki/Kelp?page=11 Note: All params values not used in path and query placeholders are appended to query parameters.

URL	https://en.wikipedia.org/{article}
Params	{"article": ["wiki", "Kelp"]}
Result	Parameter article passed as array, but placeholder doesn’t have * or + modifier, it will cause the request to fail.

Multiple value path placeholder (one or more):

URL	https://www.example.com/{post+}
Params	{"post": ["2013", "07", "16", "about"]}
Result	https://www.example.com/2013/07/16/about/

URL	https://www.example.com/{post+}
Params	{ }
Result	The required post parameter not found, it will cause the request to fail.

Multiple value path placeholder (zero or more):

URL	https://www.example.com/products/{product*}
Params	{"product": ["123", "456", "789"]}
Result	https://www.example.com/products/123/456/789

URL	https://www.example.com/products/{product*}
Params	{ }
Result	https://www.example.com/products/

Single value query placeholder:

URL	https://www.example.com/book/?page={p}
Params	{"p": 11}
Result	https://www.example.com/book/?page=11

URL	https://www.example.com/book/?page={p}
Params	[["p"]]
Result	https://www.example.com/book/?page=

Multiple value query placeholder:

URL	https://www.example.com/items/?sku={id}
Params	{"id": [123, 456]}
Result	The + and * quantifiers in the query part of the URL are not supported and will cause the request to fail.

Multiple value query parameter:

URL	https://www.example.com/products/
Params	{"id": [123, 456]}
Result	https://www.example.comm/products/?id=123&id=456 Note: There is no placeholder in url, parameter was serialized automatically.

Note

Some APIs support array values in query arguments. In these cases, you can use array values in input parameters. However, if an API handles arrays as a comma-separated list of strings, it should be converted to string explicitly. In such cases, you can utilize KelpQL transformation before constructing the URL.