Использование REST-API Digg

Программный доступ к наиболее полезным функциям Digg

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

Брайан M. Кэри, консультант по информационным системам, Triangle Information Solutions

Photo of Brian CareyБрайан Кэри (Brian Carey) является консультантом по информационным системам, специализирующимся на Java, Java EE, PHP, Ajax и смежных технологиях. Микроблог Брайана доступен по адресу http://twitter.com/brianmcarey.



14.09.2011

Что такое Digg?

Digg (http://www.digg.com) – это Web-сайт, который позволяет открывать, совместно использовать и рекомендовать контент из любой точки Интернета. Обычно это статьи из авторитетных источников новостей или записи в блоге. Затем пользователи могут голосовать "за" (digging – "выкапывать") или "против" (burying – "хоронить") представленных рекомендаций. Посты, набравшие наибольшее количество голосов, появляются на главной странице сайта.

Часто используемые сокращения

  • API: Application programming interface – интерфейс прикладного программирования
  • HTTP: Hypertext Transfer Protocol – протокол передачи гипертекстовых файлов
  • REST: Representational State Transfer – передача репрезентативного состояния
  • URL: Uniform Resource Locator – универсальный указатель ресурсов
  • XML: Extensible Markup Language – расширяемый язык разметки

Digg работает как безредакционный сайт агрегации статей. Под термином "безредакционный" я понимаю то, что популярность содержания Digg определяется исключительно путем всеобщего голосования пользователей. Считайте это демократией в социальных СМИ. Заметным исключением из этого правила стал случай, произошедший в 2007 году, когда Digg "выкопал" пост, содержащий ключ шифрования для определенных дисков HD DVD и Blu-Ray.

Как и многие сайты, относящиеся к категории социальных СМИ, Digg позволяет обсуждать предложенные статьи. Пользователи могут комментировать пост, после чего другие пользователи дают свои комментарии на их комментарии. И представьте себе: вся эта цепочка комментариев может набирать популярность, как любая статья в Интернете. Добро пожаловать в двадцать первый век!

Многие из упомянутых выше авторитетных сайтов и блогов признают важность Digg, размещая его значок на своих Web-страницах, где публикуются статьи и заметки. Как правило, этот значок помечается как Digg This! Часто он появляется рядом со значками, представляющими другие подобные сайты (Reddit, StumbleUpon и т.п.). Нажав на значок, пользователь публикует статью в Digg. А там другие могут откапывать или хоронить ее, как упоминалось выше.

Признавая важность социальных СМИ, Digg недавно ввел новую функцию Facebook Connect. Как следует из названия, Facebook Connect предоставляет пользователям Digg и Facebook возможность соединять свои учетные записи. В результате пользователи Facebook Connect могут публиковать заметки из Digg на своей странице Facebook. Кроме того, пользователи Facebook могут с помощью Facebook Connect создавать учетные записи Digg без обычного процесса регистрации.

Что такое REST?

REST – это сокращение от Representational State Transfer (передача данных о состоянии). Полное определение REST и его объяснение выходит за рамки данной статьи, но их можно найти в других местах на IBM DeveloperWorks (см. раздел Ресурсы). Здесь же достаточно сказать, что REST позволяет разработчикам получать доступ к информации и ресурсам, используя простой вызов HTTP.

Например, представьте, что компания FishinHole.com создала Web-сайт, который продает рыболовные снасти. Посетители сайта могут рассматривать различные приманки, катушки, удилища и т.п. Они делают это традиционным способом: нажимая на ссылки. Тем самым FishinHole.com делает свои услуги доступными для пользователей.

Но FishinHole.com делает свои услуги доступными и для Web-приложений, предлагая свой каталог рыболовных снастей посредством REST. Благодаря этому Web-приложение, вместо того чтобы нажимать на ссылки, получает информацию о приманках, катушках, удилищах и т.п. с помощью простых вызовов HTTP. Например, запрос http://www.fishinhole.com/catalog/rest/lures?format=xml возвращает список в формате XML всех приманок, предлагаемых компанией. Другой пример: запрос http://www.fishinhole.com/catalog/rest/item?id=343221 возвращает в формате по умолчанию сведения о позиции №343221.

Суть REST можно объяснить следующим образом: чтобы получить сведения о том или ином предмете, достаточно обратиться в нужное место посредством URL. Для целей настоящей статьи этого достаточно. REST можно представить и как упрощенный Web-сервис, но если произнести это слишком громко в определенных кругах, можно оказаться в центре бурной дискуссии.

Примечание. Я должен оговориться, что компании FishinHole.com на самом деле не существует. Так что если вы наберете любой из этих URL в строке адреса браузера, то получите сообщение об ошибке. Я предлагаю эти примеры, просто чтобы продемонстрировать формат типичного вызова REST.

Что такое API Digg?

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

API Digg принимает запросы REST (см. предыдущий раздел). Формат ответа зависит от разработчика, но ограничивается набором из XML, JavaScript Serialized Object Notation (JSON), JavaScript и Serialized PHP. Все ответы представлены в восьмибитном формате UCS/Unicode Transformation Format (UTF-8).

Когда ответ получен, разработчик анализирует его и может использовать по мере необходимости в отдельном Web-приложении.

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

Использование REST-API Digg

Как и большинство API в сфере социальных СМИ, Digg предельно прост в применении. Обладая некоторым опытом работы с упомянутыми выше технологиями, можно без проблем реализовать простой вызов API Digg.

Простой пример

Рассмотрим следующий простой пример:

http://services.digg.com/1.0/endpoint?method=story.getPopular

Достаточно просто ввести этот адрес в адресную строку своего любимого браузера и нажать Enter. Через несколько секунд вы должны увидеть на экране результат в формате XML, который выглядит как в листинге 1. Примечание. В листинге 1 из-за ограничений форматирования значение атрибута src элемента thumbnail разбито на несколько строк. На самом деле это должна быть одна строка символов:

src="http://digg.com/movies/The_real_incredibly_mundane_reason_Darth_Vader_wears_a_mask/t.jpg"

Листинг 1. Простой пример: результат
<story link="http://scifiwire.com/2009/11/the-real-incredibly-munda.php" 
submit_date="1259092461" diggs="52" id="17390757" 
comments="2" 
href="http://digg.com/movies/The_real_incredibly_mundane_reason_Darth_Vader_wears_a_mask" 
promote_date="1259150128" status="popular" media="news">
 <description>Darth Vader is one of the coolest --and coolest-looking-- characters in 
science fiction, yet much of his appearance was the result of 
nothing more than practicality. At least that's how 
Ralph McQuarrie, the legendary conceptual designer of George 
Lucas' original Star Wars films, remembers the evolution of the 
Sith's darkest Dark Lord</description>
 <title>The real, incredibly mundane reason Darth Vader wears a mask</title>
 <user name="mklopez" registered="1121877948" profileviews="128127" 
icon="http://digg.com/users/mklopez/l.png" />
 <topic name="Movies" short_name="movies" />
 <container name="Entertainment" short_name="entertainment" />
 <thumbnail originalwidth="550" originalheight="324" 
contentType="image/jpeg" src="http://digg.com/movies/
  The_real_incredibly_mundane_reason_Darth_Vader_wears_a_mask/t.jpg"
width="80" height="80" />
 <shorturl short_url="http://digg.com/d31Ay85" view_count="210" />
 </story>

Ответ будет содержать гораздо больше элементов story, чем в листинге 1. Этот листинг сокращен для экономии места.

Прежде всего заметим, что результат представлен в формате XML. Это формат по умолчанию, если формат результата не указан.

Большинство атрибутов и дочерних элементов говорят сами за себя. Тем не менее, я вкратце опишу их.

Элемент story представляет собой собственно статью, "откопанную" где-то во Всемирной паутине. Все необходимые сведения об этой статье выражены либо атрибутами, либо дочерними элементами.

Атрибут link, как следует из названия, представляет собой фактический URL самой статьи. Это постоянная ссылка на статью. Другими словами, URL должен всегда работать как указатель на статью, описываемую элементом story.

Атрибут submit_date представляет собой дату, когда статья была передана в Digg. Она выражается в формате времени UNIX®, т. е. количеством секунд, прошедших с 1 января 1970 года.

Атрибут diggs указывает, сколько раз эта статья была "откопана". Это чистый результат, т. е. общее число голосов "за" за вычетом общего числа голосов "против".

Атрибут id – это идентификационный номер статьи в Digg.

Атрибут comments соответствует числу комментариев (на самом сайте Digg), относящихся к этой статье.

Атрибут href – это постоянная ссылка на представление статьи на сайте Digg. Она отличается от link тем, что link указывает на статью на том сайте, где она фактически размещена, тогда как href указывает на представление этой статьи в Digg.

Атрибут promote_date – это дата (опять же, в формате времени UNIX) продвижения статьи в Digg. Иными словами, это время последнего подъема рейтинга данной статьи.

Атрибут status отражает текущее состояние статьи. В данном случае он имеет значение popular, поскольку на текущий момент эта статья – одна из самых популярных в Digg. Статьи со статусом popular появляются на главной странице Digg.

Атрибут media отражает тип статьи. В данном случае это новостная статья.

Элемент description представляет собой краткое изложение содержания статьи. Это нужно для того, чтобы пользователи Digg могли взглянуть на резюме статьи и решить, стоит ли читать ее целиком.

Элемент title содержит заголовок статьи.

Элемент user предоставляет информацию о пользователе, который поместил статью в Digg. Обратите внимание, что атрибуты отражают ключевую информацию о пользователе, такую как дата регистрации пользователя в Digg, сколько раз просматривался профиль пользователя и URL значка этого пользователя.

Элемент topic содержит тему статьи. В данном случае речь идет о кино (Movies). Заметим, что хотя это и не отражено в формате XML, тема на самом деле выводится из категории контейнера.

Элемент container, как я только что упомянул, является логическим родителем элемента topic. В данном случае контейнером служит Entertainment (развлечения).

Элемент thumbnail содержит ключевую информацию об эскизе, который отображается рядом с записью Digg. Если зайти на http://www.Digg.com прямо сейчас, там почти наверняка будет несколько записей Digg с эскизами. Этот элемент содержит информацию о таких эскизах, в частности, URL эскиза.

Элемент shorturl содержит сокращенный URL данной статьи. Это удобно, если вы хотите передать URL в Twitter, который поддерживает очень ограниченное число символов на твит.

Простое редактирование

Допустим, статья вам понравилась настолько, что захотелось посмотреть другие статьи из контейнера Entertainment. К счастью, Digg предоставляет API именно для этой цели.

Рассмотрим следующий URL:

http://services.digg.com/1.0/endpoint?method=story.getPopular&container=Entertainment

Он позволит получить список статей из указанной категории (в данном случае, Entertainment), которые в последнее время получили достаточно голосов, чтобы стать "популярными". Если ввести этот URL в адресную строку браузера и нажать клавишу Enter, вы увидите список статей из контейнера Entertainment.

Поддерживаемые функции

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

Получение популярных заметок

Конечную точку для получения популярных заметок (Get Popular Stories) мы уже рассматривали и, вероятно, именно ее будет использовать большинство разработчиков. Как видно из названия, эта конечная точка применяется для получения статей из Digg.

Имя соответствующего метода:

/story.getPopular

Конечно, нужно указать полный URL:

http://services.digg.com/1.0/endpoint?method=story.getPopular

Как и другие функции, она принимает спецификации того, что именно нужно получить. В данном примере таких спецификаций нет, так что Digg возвращает все популярные статьи. В примере из предыдущего раздела была указана спецификация для популярных статей из контейнера развлечений (&container=Entertainment).

Если по каким-либо причинам вы не приведете никаких спецификаций, то получите все статьи из Digg при определенных ограничениях. Этот URL будет выглядеть как тот, что приведен в предыдущем абзаце. В целях экономии полосы пропускания результат, возвращаемый из этого URL, включает только первые десять из запрашиваемых десяти статей. Количество возвращаемых статей можно увеличивать в пределах 100, используя параметр count:

http://services.digg.com/1.0/endpoint?method=story.getPopular&count=30

Этот URL возвратит 30 вместо десяти по умолчанию.

Еще один полезный параметр для списка статей позволяет извлекать самые последние статьи:

http://services.digg.com/1.0/endpoint?method=story.getUpcoming

Он возвращает XML-эквивалент того, что вы увидели бы, если вы вручную набрали следующий адрес:

http://digg.com/all/upcoming

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

http://services.digg.com/1.0/endpoint?method=story.getTop&container=Entertainment

Обратите внимание, что вместо метода getPopular здесь используется метод getTop.

Чтобы получить самые последние статьи в определенной категории, нужно заменить метод getTop в приведенном выше URL методом getUpcoming:

http://services.digg.com/1.0/endpoint?method=story.getUpcoming&container=Entertainment

Получение комментариев

Конечная точка Get Comments (Получить комментарии) возвращает список комментариев в соответствии с указаниями вызова REST. Напомним, что пользователи Digg могут комментировать присылаемые статьи. Эта функция возвращает выборку из таких комментариев, отфильтрованных в соответствии с условиями запроса.

Имя метода, соответствующего этой конечной точке: story.getComments.

Чтобы увидеть все комментарии к определенной статье, воспользуйтесь следующим URL:

http://services.digg.com/1.0/endpoint?method=story.getComments&story_id=17390757

Параметр запроса story_id обязателен и должен содержать идентификатор статьи, комментарии к которой нужно извлечь. Результат должен выглядеть как в листинге 2.

Листинг 2. Комментарии Digg: результат
<?xml version="1.0" encoding="utf-8" ?>
<events timestamp="1261234852" total="14" offset="0" count="10">
<comment date="1259165131" id="29563488" story="17390757" 
up="10" down="1" replies="1" replyto="" user="Manchildcartoon" 
level="0" root="29563488">That's not true...THAT'S IMPOSSIBLE!!!</comment>
<!-- The other 9 comments appear here -->
</events>

Этот код возвращает 10 комментариев в формате XML (помните, что Digg возвращает только 10 результатов, если явно не запросить больше). Каждый комментарий появляется в элементе comment как дочерний элемент элемента events. В приведенном выше результате показан один из комментариев – девять других выглядят точно так же. Параметры определяют дату комментариев, идентификатор статьи, идентификатор события и автора комментария. Обратите внимание, что в отличие от простого комментария событием Digg может быть и фактический диг — в этом случае событие будет отображаться в элементе digg.

Получение информации о пользователях

Функция Get Users (Получить информацию о пользователях), как и предполагает название, возвращает информацию о пользователях Digg, указанных в REST-API.

Имя соответствующего метода:

/user.getAll

С учетом этого рассмотрим следующий URL:

http://services.digg.com/1.0/endpoint?method=user.getAll&usernames=Manchildcartoon

Здесь важно отметить, что для данной функции параметр usernames обязателен. Это должен быть разделенный запятыми список имен пользователей, информацию о которых требуется получить. Результат будет выглядеть как в листинге 3.

Листинг 3. Пользователи Digg: результат
<?xml version="1.0" encoding="UTF-8"?>
<users count="1" offset="0" timestamp="1261394886" total="1" 
version="1.0"><user icon="/users/Manchildcartoon/l.png" 
name="Manchildcartoon" profileviews="565" registered="1228079424"/>
</users>

Как видите, результат содержит информацию о конкретном пользователе Digg, в том числе значок пользователя (возможно, его фотографию), дату регистрации и количество просмотров профиля пользователя.

Заключение

API Digg предлагает мощный набор функций тем пользователям, которые хотят программно обращаться к статьям, событиям и сведениям о пользователях Digg. Применяя эти функции, Web-разработчики могут обеспечить мгновенный доступ к популярному Web-контенту, не переадресовывая своих пользователей на Digg.com.

Ресурсы

Научиться

  • Оригинал статьи (EN).
  • Документация по API Digg: узнайте о том, как программно взаимодействовать с Digg и его данными с помощью формы, которую легко интегрировать в приложения или разместить на Web-сайте.
  • Web-сервисы RESTful: основы (Alex Rodriguez, developerWorks, ноябрь 2008 г.): прочтите превосходный обзор REST (EN).
  • UNIX Time Stamp.com: обзор, посвященный меткам времени UNIX и отслеживанию времени по общему количеству прошедших секунд.
  • Сертификация IBM по XML: как стать сертифицированным IBM разработчиком XML и смежных технологий.(EN)

Обсудить

Комментарии

developerWorks: Войти

Обязательные поля отмечены звездочкой (*).


Нужен IBM ID?
Забыли Ваш IBM ID?


Забыли Ваш пароль?
Изменить пароль

Нажимая Отправить, Вы принимаете Условия использования developerWorks.

 


Профиль создается, когда вы первый раз заходите в developerWorks. Информация в вашем профиле (имя, страна / регион, название компании) отображается для всех пользователей и будет сопровождать любой опубликованный вами контент пока вы специально не укажите скрыть название вашей компании. Вы можете обновить ваш IBM аккаунт в любое время.

Вся введенная информация защищена.

Выберите имя, которое будет отображаться на экране



При первом входе в developerWorks для Вас будет создан профиль и Вам нужно будет выбрать Отображаемое имя. Оно будет выводиться рядом с контентом, опубликованным Вами в developerWorks.

Отображаемое имя должно иметь длину от 3 символов до 31 символа. Ваше Имя в системе должно быть уникальным. В качестве имени по соображениям приватности нельзя использовать контактный e-mail.

Обязательные поля отмечены звездочкой (*).

(Отображаемое имя должно иметь длину от 3 символов до 31 символа.)

Нажимая Отправить, Вы принимаете Условия использования developerWorks.

 


Вся введенная информация защищена.


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=40
Zone=XML
ArticleID=757593
ArticleTitle=Использование REST-API Digg
publish-date=09142011