URL Encoding for APIs: What to Encode and What to Leave Alone

API bugs caused by URLs are usually small but expensive to debug. A space, ampersand, slash, plus sign, or non-English character can change the meaning of a query string if it is not encoded in the right place.

The common mistake is encoding the entire URL instead of encoding individual values. That turns separators like ? and & into literal text, so the server receives a different request than the one you intended.

Encode values, not structure

Treat the URL structure and the parameter values as separate things. The path, question mark, equals signs, and ampersands define the shape of the request. User-provided values are the part that usually needs encoding.

• Encode each query parameter value before appending it to the URL.
• Do not encode the protocol, host, slashes, question mark, or ampersands that separate parameters.
• Decode a captured URL once before deciding whether it is already encoded.
• Watch for plus signs because some systems treat them as spaces in form-encoded data.

Avoid double encoding

Double encoding happens when a value that already contains percent sequences is encoded again. The result may look valid, but the API receives characters such as %2520 instead of a single encoded space.

• Search logs for %25 when you expected a normal percent-encoded value.
• Compare the browser address bar with the request shown in developer tools.
• Use a decoder to inspect the final value that the server should read.
• Keep test cases with spaces, ampersands, slashes, and Unicode text.

Test small examples first

Before wiring a request into production code, build the final URL with one or two difficult values and decode it back. If the decoded values match the original inputs, your encoding boundary is probably correct.

Good URL encoding is mostly about consistency. Pick one layer of the app to encode values, document it, and avoid re-encoding the same data later.