14 июня 2016 в 11:26

API hh.ru. Быстрый старт tutorial


Полагаю, некоторые из вас знают, что у 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 на гитхабе.
Автор: @shurik2533
Похожие публикации

Комментарии (16)

  • +4
    Если кто на java будет писать, для упрощения работы с OAuth2, порекомендую библиотечку ScribeJava.
    В ней из коробки поддерживается API от hh.ru
    https://github.com/scribejava/scribejava/blob/master/scribejava-apis/src/test/java/com/github/scribejava/apis/examples/HHExample.java
    (собственно она в самом hh.ru и используется для работы со своим же API)
  • 0
    А на apigee.com можно поиграться с вашим API?
  • 0
    Спасибо за статью
    Один момент, откуда берем client_secret?
    • 0
      Генерируется автоматически при создании прижения в личном кабинете на https://dev.hh.ru
      • 0
        Спасибо.
        Правда прошелся по диагонали и понял, что в статье написано было, упустил момент.
  • +1
    Неплохое начало. Буду ждать продолжения.
  • +1
    Ребят, небольшой фидбэк.
    Полгода назад сам разбирался с вашим апи, и затупил на одной простой вещи: не принимался access token.
    Пару часов потратил, пока не понял, что нужно слово Bearer дописать.
    Если у меня подозрение, что не я один такой, так что, пожалуйста, либо в документации обратите на это внимание, либо даже проверку сделайте)
    • 0
      Спасибо за отзыв. В выдаче ошибки будет расширено описание
  • 0
    Почему у вас во всех вакансиях совпадают значения «created_at» и «published_at»?
    • 0
      Так сложилось исторически. Не используйте поле created_at — оно не описано в документации
      • 0
        Спасибо за ответ. А возможно ли другим способом получить через API реальную дату создания вакансии, а не дату ее последней публикации?
        • 0
          Нет, эта информация не возвращается
  • 0
    Насколько я понял, то обновить access_token можно только если есть приложение?
    • 0
      всё так.
      • 0
        а как обновлять если такой не нужен? Ведь только токен нужен если:
        Если приложение обращается
 только к вашему аккаунту на hh.ru
        а остальное мне даром и не нужно.
        • 0
          токен выданный в личном кабинете в dev.hh.ru действует примерно 2 недели. каждые 2 недели или чаще можно получать новый.

          если хочется получить «постоянный токен», нужно зарегистрировать приложение, провести авторизацию приложения (можно вручную, хватит curl'а), затем получить пару access token + refresh token, их можно будет по истечению 2-х недель поменять на новую пару access token + refresh token и так далее.

          ограничение времени жизни access token'а сделано по соображением безопасности.

Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

Самое читаемое Разработка