URL Encoding Best Practices for REST APIs

Why URL Encoding Matters for APIs

Proper URL encoding is critical in REST API development. Incorrectly encoded URLs can lead to broken requests, security vulnerabilities, data loss, and interoperability issues between different systems and programming languages. As an API developer, you need to understand both how to encode URLs when making requests and how to decode them when handling requests.

Encoding Path Parameters

REST APIs often use path parameters to identify resources. When these parameters contain special characters, proper encoding is essential:

// Path parameter with special characters
// Resource: "Tom & Jerry's Show"
GET /api/shows/Tom%20%26%20Jerry%27s%20Show

// Using JavaScript
const showName = "Tom & Jerry's Show";
const url = `/api/shows/${encodeURIComponent(showName)}`;

// Path with forward slash in value
// File: "documents/my report.pdf"
GET /api/files/documents%2Fmy%20report.pdf

Encoding Query Parameters

Query parameters are the most common place where encoding issues arise. Always encode both keys and values:

// Multiple parameters with special characters
GET /api/search?q=C%2B%2B%20programming&category=languages%20%26%20tools&page=1

// Using URLSearchParams (recommended)
const params = new URLSearchParams({
  q: 'C++ programming',
  category: 'languages & tools',
  page: '1'
});
const url = '/api/search?' + params.toString();

Handling Arrays and Objects in Query Strings

Different API frameworks handle array parameters differently. Here are the common conventions:

// Repeated keys (most common)
GET /api/items?tag=javascript&tag=typescript&tag=react

// Bracket notation (PHP, Rails)
GET /api/items?tags[]=javascript&tags[]=typescript

// Comma-separated (some REST APIs)
GET /api/items?tags=javascript,typescript,react

// Nested objects (bracket notation)
GET /api/search?filter[status]=active&filter[sort]=date

Content-Type and Encoding

The Content-Type header determines how request body data is encoded:

• application/x-www-form-urlencoded - Similar to URL query strings. Keys and values are encoded, spaces become +
• multipart/form-data - Used for file uploads. Each part has its own encoding
• application/json - JSON format. No URL encoding needed for the body, but the Content-Type must be set correctly

API Security Considerations

• Always validate and sanitize decoded URL parameters on the server
• Be aware of path traversal attacks via encoded sequences like %2e%2e%2f (../)
• Implement URL length limits to prevent denial-of-service attacks
• Never trust client-side encoding -- always re-validate on the server
• Watch for double-encoding attacks where malicious input bypasses filters after one round of decoding
• Use parameterized queries to prevent SQL injection even after URL decoding

Testing URL Encoding in APIs

When testing your API endpoints, include test cases for the following scenarios:

• Parameters with spaces (test both %20 and +)
• Parameters with reserved characters (&, =, ?, #)
• Parameters with Unicode characters
• Empty parameter values
• Very long parameter values
• Already-encoded input (double encoding detection)
• Parameters with null bytes (%00)