- Всё API работает по протоколу HTTPS.
- Авторизация осуществляется по протоколу OAuth2.
- Все данные доступны только в формате JSON.
- Базовый URL —
https://api.hh.ru/ - Возможны запросы к данным любого сайта группы компаний HeadHunter
- Даты форматируются в соответствии с
ISO 8601:
YYYY-MM-DDThh:mm:ss±hhmm.
В запросе необходимо передавать заголовок User-Agent, но если ваша реализация
http клиента не позволяет, можно отправить HH-User-Agent. Если не отправлен ни
один заголовок, то ответом будет 400 Bad Request.
Указание в заголовке названия приложения и контактной почты разработчика
позволит нам оперативно с вами связаться в случае необходимости.
Заголовки User-Agent и HH-User-Agent взаимозаменяемы, в случае, если вы отправите оба заголовка,
обработан будет только HH-User-Agent.
User-Agent: MyApp/1.0 (my-app-feedback@example.com)
Подробнее про ошибки в заголовке User-Agent.
Данные, передающиеся в теле запроса, должны удовлетворять требованиям:
- Валидный JSON (допускается передача как минифицированного варианта, так и pretty print варианта с дополнительными пробелами и сбросами строк).
- Рекомендуется использование кодировки UTF-8 без дополнительного экранирования
(
{"name": "Иванов Иван"}). - Также возможно использовать ascii кодировку с экранированием
(
{"name": "\u0418\u0432\u0430\u043d\u043e\u0432 \u0418\u0432\u0430\u043d"}). - К типам данных в определённым полях накладываются дополнительные условия,
описанные в каждом конкретном методе. В JSON типами данных являются
string,number,boolean,null,object,array.
Ответ свыше определенной длины будет сжиматься методом gzip.
API широко использует информирование при помощи кодов ответов. Приложение должно корректно их обрабатывать.
В случае неполадок и сбоев, возможны ответы с кодом 503 и 500.
При каждой ошибке, помимо кода ответа, в теле ответа может быть выдана дополнительная информация, позволяющая разработчику понять причину соответствующего ответа.
Более подробно про возможные ошибки.
В ответах и параметрах API можно найти ключи не описанные в документации. Обычно это означает, что они оставлены для совместимости со старыми версиями. Их использование не рекомендуется. Если ваше приложение использует такие ключи, перейдите на использование актуальных ключей, описанных в документации.
К любому запросу, подразумевающему выдачу списка объектов, можно в параметрах
указать page=N&per_page=M. Нумерация идёт с нуля, по умолчанию выдаётся
первая (нулевая) страница с 20 объектами на странице. Во всех ответах, где
доступна пагинация, единообразный корневой объект:
{
"found": 1,
"per_page": 1,
"pages": 1,
"page": 0,
"items": [{}]
}API поддерживает технологию CORS для запроса данных из
браузера с произвольного домена. Этот метод более предпочтителен, чем
использование JSONP. Он не ограничен методом GET. Для отладки CORS доступен
специальный метод. Для использования JSONP передайте параметр
?callback=callback_name.