API Я.ру (бета)

Внимание: пост для разработчиков! Представители других профессий могут быть несовместимы с текстом и проявлять при прочтении поведенческие признаки скуки.

Мы — разработчики Яндекса — внимательно слушаем, о чём нас просят пользователи, а также другие разработчики. Конечно, мы не всесильны и не можем обеспечить счастья сразу всем, но нам очень приятно, когда получается сделать что-то хорошее. Вот как сегодня. Мы начинаем публичное бета-тестирование не одного, а сразу двух сервисов:

• API для нашего любимого блогохостинга — Я.ру,
• сервиса OAuth-авторизации для этого и других наших API.

Разрабатывая их, мы не только придерживались принципов открытости и соответствия стандартам, но и дали себе волю заметно поднять «градус гиковости» — API строится на самых модных технологических принципах.

Авторизация — это начало работы с API, с неё и начнём. В качестве стандарта мы выбрали OAuth 2.0. Несмотря на то, что он пока только черновик, мы решили реализовать его по очень простой причине — это открытый стандарт, который собираются поддерживать самые развитые технологические компании мира. Его предыдущие версии реализованы, например, в Google и Twitter. Мы надеемся в будущем поддержать этот вид авторизации в других наших API, например — в Фотках (да-да, мы слышали, что вы жаловались на их сложную авторизацию!)

После авторизации с помощью API Я.ру можно программно просматривать и редактировать профиль пользователя, делиться ссылками, менять настроение, создавать сообщения в блогах и комментировать. Словом — почти всё, что можно делать на самом сервисе.

Структурно API построен по идеологии REST:

• весь сервис представлен в виде ресурсов, имеющих состояние,
• каждый ресурс имеет стандартный интерфейс доступа, основанный на методах и кодах ошибок HTTP,
• ресурсы используют URI для навигации по связанным частям системы,
• где можно, используются стандартные форматы представления данных и протоколы — в частности, Atom и AtomPub.

Мы выбрали REST, потому что он максимально отражает наши взгляды на то, каким должен быть API веб-сервиса. Стандартизованный интерфейс и открытые форматы дают разработчикам возможность использовать свои наработки и сторонние библиотеки для разных сервисов вместо того, чтобы писать абсолютно уникальный код для каждого. Со стороны же сервиса это сильно упрощает поддержку документации, а также, например, даёт возможность более удобно масштабировать сервисы и сочетать их друг с другом.

Это может показаться довольно сложным, поэтому, чтобы дать почувствовать, что на практике всё сильно проще, вот короткий пример кода на Питоне, который меняет настроение пользователя:

# -*- coding:utf-8 -*-
from urllib2 import urlopen, Request

import elementflow
import lxml.etree


ACCESS_TOKEN = 'f46606d61b9249078945599fb7192eb2'
NAMESPACES = {
  '': 'http://www.w3.org/2005/Atom',
  'y': 'yandex:data',
}
HOST = 'api-yaru.yandex.ru'


def auth_request(url, body=None):
    '''Создаёт авторизованный объект запроса.'''
    return urlopen(Request(url, data=body, headers={
        'Authorization': 'OAuth %s' % ACCESS_TOKEN
    }))

def get_link(rel):
    '''Возвращает URL нужного ресурса из профиля авторизованного пользователя.'''
    f = auth_request('https://%s/me/' % HOST)
    xml = lxml.etree.parse(f)
    namespaces = {'y': NAMESPACES['y']}
    links = xml.xpath('/y:person/y:link[@rel="%s"]' % rel, namespaces=namespaces)
    return links[0].attrib['href']

def change_mood(mood):
    '''Создаёт пост типа "смена настроения".'''
    with elementflow.xml(elementflow.Queue(), 'entry', namespaces=NAMESPACES) as xml:
        xml.element('category', {'scheme': 'urn:wow.ya.ru:posttypes', 'term': 'status'})
        xml.element('content', text=mood)
        xml.element('y:comments-disabled')
    auth_request(get_link('posts'), xml.file.pop())


if __name__ == '__main__':
    change_mood(u'Тестовое настроение')

Подробнее — в документации.

Выпуская API не в виде законченного сервиса, а бета-версией, мы приглашаем тестировать его всех заинтересованных разработчиков. Нам интересно получить от вас пожелания по функционалу и сообщения об ошибках, пишите в Клуб сервиса Я.ру. И API, и протокол OAuth, который тоже находится в стадии черновика, обязательно будут меняться, будьте к этому готовы.

За дело!

Иван Сагалаев и Григорий Бакунов, гики со стажем