Дизайн API Я.ру

Вчера мы открыли в бету API для Я.ру. Это был первый пост в корпоративном блоге Яндекса с кодом на Питоне, что даже породило фан-арт :-). Для меня этот запуск имеет большое эмоциональное значение, потому что машиночитаемый веб — мой давний интерес, и этот проект — первый неигрушечный публичный API, где я занимаюсь дизайном, и могу смотреть, как выживают на практике теоретические соображения о том, как это должно делаться.

Я говорю тут от своего лица, и чтобы не возникало ложных ощущений, должен сказать, что я это всё делаю, конечно, не один. Начинал писать собственно серверную часть Иван Челюбеев. Моя текущая роль — проектировщик и менеджер. Код пишет сейчас Костя Меренков, а со стороны Я.рушного бэкенда нам помогает Серёжа Чистович.

Этот пост — несколько заметок о том, как всё устроено внутри. Пишите в комментариях, если что-то нужно раскрыть подробнее.

Сервис над сервисом

Сам Я.ру — многоуровневая кодобаза на нескольких языках и технологиях. Серверная её часть общается с внешним для себя миром по CORBA, и поэтому не подходит для публичного API. Кроме того, публичное API поддерживать тяжелее, чем внутреннее, из-за необходимости думать про обратную совместимость. Поэтому API сервиса Я.ру — это по сути ещё один отдельный сервис, который смотрит во внешний мир через HTTP, а внутрь — через CORBA.

Сервис этот написан на Джанго. Он довольно нетипичен для джанговского сервиса, потому что не использует моделей (у него вообще нет своих собственных данных), форм и шаблонов. Тем не менее, он сделан на Джанго... для простоты. Эта шокирующая идея идёт вразрез с общим трендом в тусовке модных питонистов, где принято считать Джангу "тяжёлой" (что бы это ни значило), и отказываться от неё сразу же, как только удастся найти хотя бы один компонент, который в проекте не нужен. У нас всё наоборот. Поскольку мы давно привыкли отлаживать, пакетировать, деплоить и мониторить Джанго-проекты, это делать проще, чем уживаться с любым новым фреймворком. И даже в отсутствии "более основных" компонентов сильно помогают знакомые полезные вещи: urlconf, middleware, модель запросов и ответов с вьюхами, дебагные страницы.

REST

Учитывая моё отношение к REST, вряд ли должно быть сюрпризом, что этот API именно такой. Если совсем честно, это было даже постановкой задачи. То есть не было так, как обычно происходит в статьях по проектированию: собрались люди и стали думать, какими средствами решать задачу "сделать API для Я.ру" и выбрали лучшую технологию для задачи. Это скучно! Мы собрались делать модный REST'овый API, а для чего именно — не суть важно :-).

Ресурсы и операции

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

Операции над ресурсами есть очевидные, а есть не очень.

Очевидное — это например изменение данных профиля. Оно происходит как GET ресурса, изменение в XML нужных элементов и PUT всего профиля обратно на то же место. Здесь мы какое-то время думали над тем, чтобы поддержать обработку на входе "частичных представлений": поскольку полный профиль пользователя содержит довольно много полей, возможно клиенту было бы удобней передавать не все поля, а только те, что меняются. Тогда XML'ка могла бы выглядеть буквально как <person xmlns="yandex:data"><name>Новое имя</name></person>. Но это оказалось хлопотно на связке между API и бэкендом, и мы забросили идею. Поэтому руками составлять XML не надо, его надо считывать и менять.

К неочевидным операциям относятся те, которые в Я.ру делаются по сайд-эффекту создания поста: подружение/раздружение, смена настроения, присоединение к клубам. Например очевидным способом подружиться был бы POST человека (в виде URI или документа) в свою коллекцию друзей, но сейчас это делается POST'ом поста специального типа в свой фид. И хотя прямую операцию можно поддержать технически, создавая при этом пустой пост, этого делать не хочется намеренно. Потому что идеология Я.ру в том, чтобы всё интересное происходило во френдленте. А пустой пост — это не интересно, это спам.

Вот прямо сейчас я понял, что это не отражено чётко в нашей документации.

Адресуемость и навигация

REST диктует, что все ресурсы должны иметь свой URI. А вот что часто упускается, так это что генерацию этих URI должен брать на себя по возможности сервер, а не клиент. То есть когда вы получаете GET'ом представление ресурса, в нём должны быть ссылки, URI-шаблоны и формы, по которым клиент понимает, куда и с чем он может обращаться дальше. На практике с этим есть две проблемы:

• многих людей эта идея искренне удивляет и даже пугает, все привыкли составлять URL'ы из кусочков;
• нормальных библиотек, способных обрабатывать URI templates, мало (под Питон, кажется, вообще нет)

Однако нам тут повезло, у нас все юзкейсы укладываются просто в обычные URL-ссылки. В итоге, пользуясь ярушным API, клиенту достаточно знать один входной URL: https://api-yaru.yandex.ru/me/, а всё остальное достижимо по возвращаемым ссылкам:

• /me/ редиректит на URL текущего залогиненного человека /person/<uid>/
• /person/<uid>/ содержит ссылки на посты, список друзей, списки клубов
• длинные списки содержат ссылки на следующие страницы
• из клубов есть обратные ссылки на своих членов
• и т.д.

Если вы пользуетесь этим API, и нашли, что вам приходится генерировать ссылку из кусочков — пишите, возможно мы просто упустили какую-то ссылку.

Форматы данных

REST, опять-таки, диктует, чтобы для представлений ресурсов использовались по возможности известные стадартные форматы данных. Если так получается — это сказка. Всего лишь по одному заголовку Content-type клиент полностью понимает, как работать с этим ресурсом.

Поэтому для работы с блог-контентом — лентами и постами — мы выбрали AtomPub, который специально для этого и создавался. Этот же формат используют, например, Blogger и WordPress. Теоретически это означает, что с Я.ру должны заработать клиенты вроде Windows Live Writer и BlogJet. Хотя конечно надо будет поработать над интероперабельностью и подпилить что-то в паре мест. Если кому интересно поотлаживать это с клиентской стороны — опять таки пишите!

Что интересно, что изначально, неблоговый контент — профили людей — тоже были выражены через AtomPub. Штука в том, что он явно позволяет расширять набор атрибутов записей. В постах мы используем это, чтобы передавать чисто ярушные атрибуты: уровень доступа и запрещённость комментариев. Но принципиально это значит, что через Atom можно выразить что угодно. В итоге довольно долго профили у нас были такими вырожденными "постами", в которых большая часть контента была кастомной.

Под конец, буквально за неделю до запуска, мы всё же решили, что профиль — это не пост, и особенной пользы от Atom в этом месте нет. В итоге придумали свой кастомный формат. Это не очень хорошо, и я с удовольствием послушаю идеи, какие известные форматы, выражающий понятия "профиль человека" и "клуб по интересам", можно поддержать. Пока я лениво думаю над тем, чтобы выдавать профиль в формате text/x-vcard, а списки друзей в text/directory или FOAF.

Что нам даёт вся эта REST'овость? Я пока не знаю. Отчасти, это как раз эксперимент, чтобы понять, какие обещания REST реально воплощаются, а каким ещё надо помогать. Например, если блог-клиенты заработают с Я.ру, я буду считать это значительным достижением.

Если пофантазировать, то ещё может хорошо сработать наличие глобально универсального машиночитаемого идентификатора человека. Например, в API фоток, который тоже REST'овый, можно будет реализовать функциональность "добавить в любимые авторы", основываясь как раз на ярушных URI...

OAuth

С авторизацией мы, по сути, обогнали всех :-). Мы реализовываем драфт OAuth 2.0, и я специально употребляю (кривой) глагол несовершенного вида, потому что мы апдейтим реализацию под новые ревизии драфта сразу, как только они выходят. Пока разрабатывались, их сменилось уже три :-). Теперь, после публикации, обновляться будет сложнее, потому что придётся думать про обратную совместимость.

С точки зрения реализации это тоже отдельный сервис. Тоже написан на Джанго, но по-своему интересен, например тем, что в качестве хранилища использует только Redis. Но это, наверное, отдельная история.