Permalink
116 lines (86 sloc) 6.31 KB

Общая информация

  • Всё 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

Данные, передающиеся в теле запроса, должны удовлетворять требованиям:

  • Валидный 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": [{}]
}

CORS (Cross-Origin Resource Sharing)

API поддерживает технологию CORS для запроса данных из браузера с произвольного домена. Этот метод более предпочтителен, чем использование JSONP. Он не ограничен методом GET. Для отладки CORS доступен специальный метод. Для использования JSONP передайте параметр ?callback=callback_name.

Внешние ссылки на статьи и стандарты