Guidelines for encoding API call values

Why encoding is important for API calls

Sending unencoded data to an API - even inside JSON - can introduce both security and functional risks:

• Injection attacks: Special characters in raw input can be exploited to alter API behavior or execute malicious commands.

• Broken parsing: Reserved characters ; / ? : @ & = + $ , can corrupt the request structure or cause unexpected errors.

• Data integrity issues: APIs may misinterpret unencoded values, leading to incorrect processing or unintended data exposure.

Encoding ensures that all values are transformed into a safe, predictable format before transmission, neutralizing special characters and preventing malicious input. Encoding at the point of API invocation is a defense-in-depth measure aligned with OWASP recommendations. It mitigates injection risks and ensures consistent, secure communication with external services.

Characters not allowed in URLs

The following characters are not allowed in URLs:

• < > "

• ASCII/Unicode characters 1 through 31

• The pipe character |

• The null character \0

Relative URLs not allowed

Relative URLs ( ./ ../ ) are not supported. For example:

https://sample.com/EnterpriseConsole/BPMUITemplates/Default/NextGenForms/../Repository/Sample.aspx

In this example, the ../ between NextGenForms and Repository represents a Relative Path Traversal vulnerability, which is part of the OWASP Top 10 vulnerabilities.

Required action

If your code currently sends raw values (whether hardcoded, user-entered, or retrieved from a database) directly to an API without encoding, this is considered an insecure practice and must be corrected.

Steps to encode API parameters

1. Identify all API invocation points in your code.

2. Apply encoding to every parameter or variable passed to the API method:

   • Use standard encoding functions such as URLEncode, HTMLEncode, or language-specific safe encoding libraries.

   • Ensure that encoding occurs at the final step before invoking the API - regardless of the value’s origin (hardcoded, user input, or retrieved from storage).

3. Validate the encoded output to ensure the payload structure and formatting remain correct.

Sample scenarios

Web API configuration

If the value of the Request URI contains parameter values, those values must be encoded.

Consider the Request URI: api/performaction?actionid={Id}&actionvalue={"CompanyName":"S & A Associates", "Location":"USA"}&actionname=update

In this example, there are three parameters:

• actionid - set to a dynamic placeholder {Id} at runtime

• actionvalue - contains a JSON string

• actionname - a simple static value

The actionvalue parameter contains unsupported characters such as double quotes (") which are not allowed in URLs. Additionally, the ampersand (&) used in actionvalue parameter is a reserved URL character used to separate parameters, causing the request to behave differently at runtime.

Correct approach

Encode the parameter value before using it in the URI. Only the parameter value part should be URL-encoded. After encoding, the URI becomes:

api/performaction?actionid={Id}&actionvalue=%7B%22CompanyName%22%3A%22S%20%26%20A%20Associates%22%2C%20%22Location%22%3A%22USA%22%7D&actionname=update

Important: The value for actionid ({Id}) is not encoded because it represents a dynamic placeholder that will be substituted at runtime. If a placeholder is not intended to be dynamic, it should be encoded as well (e.g., {Id} → %7BId%7D).

Web API called from Forms

If the API is called from Form scripts, use the following approach to encode parameter values before invoking the Web API:

let rawValue = "{\"CompanyName\":\"S & A Associates\", \"Location\":\"USA\"}";

// Encode before sending

let encodedValue = encodeURIComponent(rawValue);

let webAPIUrl =

"https://sample.com/api/performaction?actionid=12&actionvalue=" +

encodedValue +

"&actionname=update";

Web API called from Scripts

If Web API parameter values are created inside Workflows or generated through scripts, they must be encoded before being passed to the Web API activity.

string rawValue = "{\"CompanyName\":\"S & A Associates\", \"Location\":\"USA\"}";

// Encode before sending

string encodedValue = HttpUtility.UrlEncode(rawValue);

Use the encoded value as the Web API parameter value if the parameter requires URL encoding.

For example, if the Web API is defined as: https://sample.com/api/performaction?actionid=12&actionvalue={actionvalueparameter}&actionname=update

then actionvalueparameter must be set to the encoded value.