Полагаю, некоторые из вас знают, что у hh.ru есть открытый API (мы рассказывали о нем тут и тут), который используем не только мы, но и сторонние разработчики. С его помощью, например, можно очень детально анализировать рынок на больших объемах актуальных данных.

Я задумал серию из двух статей: в этой покажу, как можно быстро и просто начать использовать API, а в следующей сделаю небольшой проект, рекомендующий актуальные вакансии по вашему резюме.

Сначала вкратце о том, что вообще есть в нашем API, где и как его используют.

Возможности API

Чтобы быстро получить представление о возможностях API, обратите внимание, например, на наши мобильные приложения для соискателя (Android, iOS) и работодателя (Android, iOS). Они работают через API.

Например, внешние разработчики могут получить все актуальные и архивные вакансии с зарплатами и остальными деталями. А это почти 400 тыс. живых вакансий и еще черт знает сколько архивных. Желающие проанализировать рынок, поиграться с большим количеством реальных данных — вам сюда.

Через API работает поиск по вакансиям. Доступны различные справочники: регионы, используемые на сайте, специализации работников, отрасли компаний, станции метро и прочее. Для авторизованных пользователей доступна работа с вашими вакансиями или резюме: в зависимости от того, работодатель вы или соискатель. Для работодателей есть поиск по вакансиям и возможность работы с ними.

За более детальной информацией обращайтесь к нашей документации.

Как работает API?

Всё взаимодействие происходит про протоколу HTTPS в лучших традициях REST. Получаем что-то — делаем GET-запрос, удаляем — DELETE, создаем — POST, редактируем — PUT. Обмен данными производится в формате JSON. Некоторые операции доступны без авторизации, другие — нет. Авторизованный пользователь может выступать в роли работодателя или соискателя. От этого зависит, какие методы ему доступны. Для авторизации используется протокол OAuth2 (о том, как это сделать, я объясню на пальцах ниже). Работать можно с данными любого из наших сайтов. Детали в разделе «Общая информация» документации.

Начало работы

Для того чтобы начать работать с данными, доступными без авторизации, вам ничего не потребуется. Смотрим в документации, какие методы можно использовать, делаем запрос — получаем данные. Например, если хочется посмотреть вакансии

curl -k -H 'User-Agent: api-test-agent' 'https://api.hh.ru/vacancies'

Следует обратить внимание, что нужно передавать заголовок User-Agent. Без него работать не будет.

Для поиска вакансий можно задавать разные параметры.
Так, например, можно поискать вакансию по ключевому слову Java в Москве у станции метро «Алексеевская»

curl -k -H 'User-Agent: api-test-agent' 'https://api.hh.ru/vacancies?text=java&area=1&metro=6.8'

Значения area и metro можно получить из справочников.

Авторизация

Как уже было сказано, для авторизации используется протокол OAuth2.
Чтобы делать что-то из-под пользователя, для него требуется получить токен и передавать этот токен в заголовке при запросе. Для получения токена для своего пользователя достаточно его сгенерировать в интерфейсе API. Заходим в личный кабинет на https://dev.hh.ru и нажимаем на кнопку «Сгенерировать токен».

Чтобы остальные пользователи могли выполнять действия в вашем приложении, это приложение необходимо сначала завести в личном кабинете. Добавляем приложение, указав redirect URI. На этот адрес пользователь будет автоматически возвращаться после авторизации.

После добавления приложения, ему будут присвоены Client ID и Client Secret.

Как работает авторизация?

В своем приложении вы размещаете ссылку на авторизацию, указывая в ней Client ID приложения, например,

https://hh.ru/oauth/authorize?response_type=code&client_id=LOTHHN3BSET0I7IQNF3N5I0362AE1D14I6M74CAIQ5H49F7MT4PLMTVV7JTOA6QA

Когда пользователь переходит по этой ссылке, для него на нашей стороне генерируется специальный код. И наш сайт перенаправляет пользователя обратно в ваше приложение (по redirect URI, который был указан при регистрации приложения), добавив к адресу вашего приложения параметр, содержащий код. Например:

http://yourapphost/?code=J2CO4TM7PK58NNVFCJSLPMML15IKQERD5CT2L8VGK82Q333ILAKQ28BPURIO1LG8

После этого вы вытаскиваете из этого адреса code и используете его для получения токена, сделав POST-запрос в API, передав code, client_id и client_secret.

curl -k -X POST -H 'User-Agent: api-test-agent' -d 'grant_type=authorization_code&client_id=LOTHHN3BSET0I7IQNF3N5I0362AE1D14I6M74CAIQ5H49F7MT4PLMTVV7JTOA6QA&client_secret=JS33UVG3J6JANNEATPND57BME23BKDCPP2UH1NB0C21HUMNGS5T71AVP6P24E0EI&code=J2CO4TM7PK58NNVFCJSLPMML15IKQERD5CT2L8VGK82Q333ILAKQ28BPURIO1LG8' https://hh.ru/oauth/token

В ответ вы получите json, содержащий токен (поле access_token):

{
  "access_token": "VTEJ4PDD8R4MHEO7LTQM6RLEGJ1O8B1F79TGF45LIDQD11K50HMMBETB47BBCMQ1",
  "token_type": "bearer",
  "expires_in": 1209599,
  "refresh_token": "OARLQNLT6JSMDI88CO5QIP35OOSQUTOO9IQNT20MOMAHE4H8SGPM7LQUAP8EO1G6"
}

Это всё. Далее, выполняя запросы в API с заголовком Authorization: Bearer your_access_token, вы будете выполнять действия из-под пользователя. Чтобы на каждый запрос не выполнять авторизацию, сохраняйте у себя access_token.

Вот, например, запрос для получения списка резюме текущего пользователя:

curl -k -H 'Authorization: Bearer VTEJ4PDD8R4MHEO7LTQM6RLEGJ1O8B1F79TGF45LIDQD11K50HMMBETB21BBCMQ1' -H 'User-Agent: api-test-agent' https://api.hh.ru/resumes/mine

Следует учесть, что у токена есть срок жизни, указанный в поле expires_in, после истечения которого токен надо обновить.

API постоянно растет, в нем реализуется всё больше новых возможностей. Если вам сильно не хватает какого-то функционала, есть пожелания или вы нашли ошибку, то напишите нам в issues на гитхабе.