Подходит к концу время жизни первой версии нашего API. Для тех, кто еще не перевёл свои приложения на новую версию, мы подготовили руководство по миграции.
Самое, что вероятно бросается в глаза — в новой версии нет 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`, мы применили фильтр к коллекции и тем самым получили результаты поиска по вакансиям.
Полный список параметров доступен в одноименном разделе документации.
Можно получить отдельный элемент коллекции, в данном случае вакансию: 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.
Для поиска вам необходимо сделать GET-запрос к ресурсу, передав необходимые query-параметры. Для получения отдельной вакансии — сделать GET-запрос за отдельным элементом: GET /vacancies/7760476 (https://api.hh.ru/vacancies/7760476.
Также раньше у нас был отдельный адрес для получения вакансий конкретной компании, теперь это доступно через поиск: GET /vacancies?employer_id=1455 https://api.hh.ru/vacancies?employer_id=1455
Справочники
Для осуществления запроса к поиску, а также для понимания ответов мы выдаём справочники наших сущностей: тип занятости, график работы, валюты, опыт работы. Раньше это было доступно по отдельным адреса:
GET /1/json/employment/GET /1/json/schedule/GET /1/json/experience/GET /1/json/currency/
Теперь мы объединили все эти небольшие справочники в один ресурс `/dictionaries` api.hh.ru/dictionaries. (описание в документации: github.com/hhru/api/blob/master/docs/dictionaries.md).
Отдельные справочники, содержащие большое количество значения (специализации, регионы, метро) мы оставили по отдельным адресам:
GET /specializations— api.hh.ru/specializationsGET /metro— api.hh.ru/metroGET /areas— api.hh.ru/areas
Специализации были объединены с профессиональными областями (раньше это было два разных адреса: field и specialization).
Регионы были переименованы в /areas — api.hh.ru/areas.
Авторизация и новые сервисы
Но HeadHunter API не ограничивается поиском вакансий и сопутствующими справочниками. В новой версии доступна авторизация, просмотр откликов и многое другое. Это выходит за рамки статьи про миграцию, но описание всех этих методов доступно в нашей документации. Читайте, пробуйте, пишите нам, следите за новостями!
Автор: mikesub
