Лучшие практики URL-кодирования для REST API

Почему URL-кодирование важно для API

Правильное URL-кодирование играет ключевую роль в разработке REST API. Некорректно закодированные URL могут привести к сбоям запросов, уязвимостям безопасности, потере данных и проблемам совместимости между разными системами и языками программирования. Как разработчику API, вам необходимо понимать как кодировать URL при отправке запросов, так и декодировать их при обработке входящих запросов.

Кодирование параметров пути

REST API часто используют параметры пути для идентификации ресурсов. Когда такие параметры содержат специальные символы, правильное кодирование становится обязательным:

// Параметр пути со специальными символами
// Ресурс: "Tom & Jerry's Show"
GET /api/shows/Tom%20%26%20Jerry%27s%20Show

// С использованием JavaScript
const showName = "Tom & Jerry's Show";
const url = `/api/shows/${encodeURIComponent(showName)}`;

// Путь со слэшем в значении
// Файл: "documents/my report.pdf"
GET /api/files/documents%2Fmy%20report.pdf

Кодирование параметров запроса

Параметры запроса — это место, где проблемы с кодированием возникают чаще всего. Всегда кодируйте как ключи, так и значения:

// Несколько параметров со специальными символами
GET /api/search?q=C%2B%2B%20programming&category=languages%20%26%20tools&page=1

// С использованием URLSearchParams (рекомендуется)
const params = new URLSearchParams({
  q: 'C++ programming',
  category: 'languages & tools',
  page: '1'
});
const url = '/api/search?' + params.toString();

Обработка массивов и объектов в строках запроса

Разные фреймворки API обрабатывают параметры-массивы по-разному. Вот наиболее распространённые соглашения:

// Повторяющиеся ключи (наиболее распространённый вариант)
GET /api/items?tag=javascript&tag=typescript&tag=react

// Скобочная нотация (PHP, Rails)
GET /api/items?tags[]=javascript&tags[]=typescript

// Значения через запятую (некоторые REST API)
GET /api/items?tags=javascript,typescript,react

// Вложенные объекты (скобочная нотация)
GET /api/search?filter[status]=active&filter[sort]=date

Content-Type и кодирование

Заголовок Content-Type определяет, как кодируются данные тела запроса:

• application/x-www-form-urlencoded — аналогично строкам запроса URL. Ключи и значения кодируются, пробелы превращаются в +
• multipart/form-data — используется для загрузки файлов. Каждая часть имеет собственное кодирование
• application/json — формат JSON. URL-кодирование тела не требуется, но заголовок Content-Type должен быть установлен корректно

Аспекты безопасности API

• Всегда проверяйте и очищайте декодированные параметры URL на стороне сервера
• Помните об атаках обхода пути (path traversal) через закодированные последовательности вроде %2e%2e%2f (../)
• Устанавливайте ограничения на длину URL для защиты от атак типа «отказ в обслуживании» (DoS)
• Никогда не доверяйте кодированию на стороне клиента — всегда выполняйте повторную проверку на сервере
• Остерегайтесь атак двойного кодирования, когда вредоносный ввод обходит фильтры после одного цикла декодирования
• Используйте параметризованные запросы для защиты от SQL-инъекций даже после декодирования URL

Тестирование URL-кодирования в API

При тестировании эндпоинтов вашего API включите тестовые сценарии для следующих случаев:

• Параметры с пробелами (проверьте как %20, так и +)
• Параметры с зарезервированными символами (&, =, ?, #)
• Параметры с символами Unicode
• Пустые значения параметров
• Очень длинные значения параметров
• Уже закодированный ввод (обнаружение двойного кодирования)
• Параметры с нулевыми байтами (%00)