Миграция на новую версию API

Подходит к концу время жизни первой версии нашего API ^[1]. Для тех, кто еще не перевёл свои приложения на новую версию, мы подготовили руководство по миграции.

Самое, что вероятно бросается в глаза — в новой версии нет XML. Да, мы оставили только JSON, но этим всё не ограничивается.

REST

При проектировании API мы следовали REST-подходу в именовании URL’ов и использовании возможностей HTTP-протокола.

Если кратко, то в ответах нашего API помимо стандартных 200, 302, 403, 404 и 500 статусов можно увидеть: 201, 204, 405, 429, 503 и некоторые другие. Клиент API должен уметь корректно их обрабатывать: не делать бессмысленные повторы при 429 и/или 400 и не падать от получения 503.

При именовании URL'ов мы использовали термины «коллекция» и «элемент коллекции», а непосредственно действия выражаем при помощи HTTP-методов.

Теперь для осуществления поиска по вакансиям вместо обращения к /1/json/vacancy/search/ появился адрес коллекции «Вакансии»: /vacancies.

Сделав GET-запрос по этому адресу, можно получить как полную коллекцию (все вакансии на сайте), так и какой-то срез, указав query-параметры: GET /vacancies?text=голова. Указав параметр `text`, мы применили фильтр к коллекции и тем самым получили результаты поиска по вакансиям.

Полный список параметров доступен в одноименном разделе документации ^[2].

Можно получить отдельный элемент коллекции, в данном случае вакансию: GET /vacancies/7760476.

У ресурса-коллекции могут быть также подколлекции, какие-то предустановленные срезы всей коллекции. GET /vacancies/favorited вернет те вакансии, которые добавлены у авторизованного пользователя, в «отобранные».

Чтобы добавить вакансию в «отобранные», необходимо добавить вакансию в соответствующую подколлекцию:

PUT /vacancies/favorited/{vacancy_id}


Чтобы убрать, необходимо удалить ее из этой коллекции.

DELETE /vacancies/favorited/{vacancy_id}


Запросы PUT и DELETE являются идемпотентными: если вы попробуете «отобрать» вакансию, которая уже находится в отобранных, PUT вернёт 204, тем самым ответив: «Вы хотите, чтобы эта вакансия была в отобранных? Без проблем. Она в отобранных». Даже если она уже там была. Также и с удалением.

Чтобы создать вакансию (эта функциональность еще не реализована, но запланирована) необходимо будет сделать запрос POST /vacancies, указав в теле параметры создаваемой вакансии. Главное отличие POST от PUT заключается в том, что первый не идемпотентен, то есть при повторном запросе будет попытка создать еще одну вакансию.

В итоге: корректное и широкое применение HTTP-методов, HTTP-кодов и именование URL’ов в соответствии c понятиями: коллекция, подколлекция и элемент коллекции — в нашем понимание и есть REST.

Пагинация и коллекции

Еще немного про коллекции. Все коллекции, которые поддерживают пагинацию (резюме, вакансии, компании и все их подколлекции) выглядят единообразно и имеют корневой объект вида:

{
  "found": 0,
  "per_page": 20,
  "page": 0,
  "pages": 1,
  "items": []
}

К любому запросу коллекции можно в параметрах указать page=N&per_page=M. Нумерация идёт с нуля, по умолчанию выдаётся первая (нулевая) страница с 20 объектами на странице.

Версионность

Мы убрали версионность, в API теперь нет префикса в адресе: /1/.... Все URL идут от корня: https://api.hh.ru/dictionaries. Со временем данные будут расширяться, всегда обеспечивая обратную совместимость. Исключения из этого правила могут быть только в двух случаях:

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

Меньше «хардкода»

В том месте, где мы выдаём значение, которое представляет собою сущность, доступную в нашем API, мы предоставляем полную ссылку, чтобы избавить вас от необходимости «хардкодить» в вашем приложении адреса.
К примеру, в поиске вакансий:

{
  "items": [
    {
      "url": "https://api.hh.ru/vacancies/1337"
    }
  ]
}

Получив результаты поиска вам нет необходимости самим конструировать ссылку для получения полной информации о вакансии, вам достаточно взять значение ключа url.

Поиск и просмотр вакансий

Теперь о самих данных. Основное и самое популярное использование нашего API — это поиск и выдача вакансий.
Раньше это было доступно по адресам /1/json/vacancy/search/ и /1/json/vacancy/{vacancy_id} соответственно. Теперь, следуя REST-подходу, мы объединили это в коллекцию /vacancies ^[3].

Для поиска вам необходимо сделать GET-запрос к ресурсу, передав необходимые query-параметры. Для получения отдельной вакансии — сделать GET-запрос за отдельным элементом: GET /vacancies/7760476 (https://api.hh.ru/vacancies/7760476 ^[4].

Также раньше у нас был отдельный адрес для получения вакансий конкретной компании, теперь это доступно через поиск: GET /vacancies?employer_id=1455 https://api.hh.ru/vacancies?employer_id=1455 ^[5]

Справочники

Для осуществления запроса к поиску, а также для понимания ответов мы выдаём справочники наших сущностей: тип занятости, график работы, валюты, опыт работы. Раньше это было доступно по отдельным адреса:

• GET /1/json/employment/
• GET /1/json/schedule/
• GET /1/json/experience/
• GET /1/json/currency/

Теперь мы объединили все эти небольшие справочники в один ресурс `/dictionaries` api.hh.ru/dictionaries ^[6]. (описание в документации: github.com/hhru/api/blob/master/docs/dictionaries.md ^[7]).

Отдельные справочники, содержащие большое количество значения (специализации ^[8], регионы ^[9], метро ^[10]) мы оставили по отдельным адресам:

• GET /specializations — api.hh.ru/specializations ^[11]
• GET /metro — api.hh.ru/metro ^[12]
• GET /areas — api.hh.ru/areas ^[13]

Специализации были объединены с профессиональными областями (раньше это было два разных адреса: field и specialization).
Регионы были переименованы в /areas — api.hh.ru/areas ^[13].

Авторизация и новые сервисы

Но HeadHunter API не ограничивается поиском вакансий и сопутствующими справочниками. В новой версии доступна авторизация ^[14], просмотр откликов ^[15] и многое другое. Это выходит за рамки статьи про миграцию, но описание всех этих методов доступно в нашей документации ^[16]. Читайте, пробуйте, пишите нам, следите за новостями!

Автор: mikesub

Источник ^[17]