How-to Guide: Handling Special Characters in Request Fields

Supported Characters in API Fields

The API supports the following special characters in most fields, provided they are encoded or escaped appropriately:

Supported Characters:

~, #, &, @, /, ;, ", £, $, (, ), -, _, +, ¤, ',' (comma), '.' (full stop), ' ' (space)

Field-Specific Guidelines:

  1. Free-Text Fields (e.g., Names, Descriptions):

    • Fully support the characters listed above.

    • Encoding is required for characters such as ", &, or / in certain contexts (e.g., JSON, URLs).

  2. Identifiers or Codes:

    • Typically restricted to alphanumeric characters, _, and -.

    • Avoid using spaces or special symbols unless specified in the field's documentation.

  3. Currency Fields:

    • Support symbols like £, $, and ¤. Ensure these characters are encoded if part of the request body or URL.

  4. Address Fields:

    • Commas (,), periods (.), and slashes (/) are supported to allow complex address structures.

Handling Special Characters

To avoid issues during integration:

  • Use URL encoding for parameters passed in URLs (e.g., replace spaces with %20, # with %23).

  • For JSON requests, ensure proper escaping of characters like quotes (") or backslashes (\) according to JSON standards.

  • When working with HTML content, escape characters such as <, >, and & to prevent rendering or injection issues.

Encoding Special Characters

When sending data that may include special characters, such as user input, item descriptions, or any free-text fields, it’s important to ensure that the data is properly encoded.

1. URL Encoding

For URL parameters or when passing data in a URL, it is necessary to URL-encode any special characters. For example:

  • Replace spaces with %20

  • Replace < with %3C

  • Replace > with %3E

URL encoding can be achieved using the urlencode() function in most programming languages before sending the request.

2. HTML Escaping

If the request body is in HTML format, special characters like <, >, &, and quotes need to be escaped to prevent issues with HTML rendering. Use htmlspecialchars() or a similar function in your programming language to escape special characters.

3. JSON Encoding

For JSON-based requests, ensure that all special characters in string fields are properly escaped according to the JSON standard. This is typically done automatically by JSON libraries. For example:

  • \n (newline)

  • \t (tab)

  • \" (quote)

Request Validation

All incoming requests are validated for potentially harmful or malformed content. This includes checking for:

  • HTML tags

  • SQL injection attempts

  • XSS payloads

  • Invalid or unsupported characters

If any issues are detected, a 400 Bad Request error is returned with a message indicating the issue.

Example Request

Here’s an example of sending a POST request with encoded special characters to create an order:

POST Request to Create Customer Order:

POST https://axacute-api.azure-api.net/customerorders

Content-Type: application/json

Authorization: Bearer <your-auth-token>

{

"co_num": "CO20250108008",

"cust_name": "John & Mary <Branch 1>"

}

In the example above, the cust_name includes:-

  • an & character, which must be properly encoded in the request.

  • contains special HTML characters (<, >), which should be escaped if this is HTML content.

Error Handling

If the API receives a request with invalid or improperly encoded data, it will respond with an error message indicating the issue. For example:

Error Response for Invalid Special Characters

{

"error": "Invalid Input",

"message": "The 'cust_name' field contains unsupported characters."

}

In such cases, ensure that the data is properly encoded or escaped before resubmitting the request.

Supported Character Sets

The API supports UTF-8 encoded content. Ensure that all request bodies are UTF-8 encoded to avoid issues with character representation.

Guidelines for Specific Fields

Certain fields may have additional validation or restrictions on the use of special characters. Here are a few examples:

Order Fields

  • Order Number: Alphanumeric only. Special characters such as # or & are not allowed.

  • Item Descriptions: Can include special characters but should be HTML-escaped if necessary.

Customer Data Fields

  • Customer Name: Special characters like &, ", and ' are allowed but should be encoded properly.

Address Fields

  • Street Address: Special characters such as #, /, , are allowed. Avoid using special characters like &, <, >, which may cause rendering issues in web interfaces.

Data Transformation

In certain scenarios, special characters might need to be transformed before they are passed to the underlying system or database. This may involve:

  • Replacing unsupported characters with placeholders (e.g., converting & to and).

  • Stripping out problematic characters from fields.

Please consult with the your technical team or third-party vendor if you encounter any specific cases where transformation is needed.

Conclusion

To ensure smooth integration with the API, special characters must be properly encoded and validated before submitting data. Follow the guidelines above for URL encoding, HTML escaping, and JSON encoding to ensure data integrity and avoid errors in the integration process.