Eventflow API :: Wordpress plugin This plugin connects to Eventflow API server and performs various NLP-related tasks. Visit http://www.eventflow.ru for more information. Author: Kosta Sokolov (vtqveant@gmail.com) Руководство пользователя Инструкции по установке 1. Вы скачиваете плагин с сайта http://www.eventflow.ru или из другого места (как распространяются WP-плагины?) 2. Устанавливаете его на свой WP. Все готово. В процессе установки произойдет следующее: а) Плагин уже знает Consumer Key и Consumer Secret (зашито внутрь), эти параметры идентифицируют этот плагин как приложение, работающее с API (вид Eventflow API плагина вообще, возможно, его версию, но не конкретную его инсталляцию). б) Плагин обратится к Eventflow API по адресу https://api.eventflow.ru/oauth/request_token для получения Request Token (запрос на получение доступа). в) Сразу же вслед за этим плагин обратится к Eventflow API по адресу https://api.eventflow.ru/oauth/access_token, чтобы обменять Request Token на Access Token. Это т.н. двухходовый OAuth, не требующий участия зарегистрированного пользователя Eventflow API для подтверждения доступа плагина к своим данным (т.к. пока их просто нет). г) Плагин зафиксирует полученные Access Token и Access Secret в таблице в БД, в которой WP хранит настройки плагинов, и далее будет пользоваться ими для подписи всех дальнейших запросов к Eventflow API. Т.о. конкретный экземпляр плагина будет всегда однозначно идентифицироваться в рамках Eventflow API. Примечания: * Для бесплатной версии вводится ограничение на число запросов (50 в день). * Для пользователя все первоначальные взаимодействия происходят незаметно. * В дальнейшем будет сделана привязка плагинов к тарифным планам и потребуется подтверждение пользователя для того, чтобы запросы от конкретного экземпляра плагина были связаны с пользователем, его квотами и платежами. * Вы не можете самостоятельно изменить Access Token и Access Secret, для этого потребуется повторить процедуру выдачи прав доступа плагину. * При обновлении плагина (при появлении сообщения "Доступна новая версия плагина" в административном интерфейсе WP) плагин получит новые Consumer Key и Consumer Secret, процедура получения прав доступа к Eventflow API будет осуществлена автоматически. (При реализации привязки плагина к тарифному плану необходимо обеспечить наследование квот и пр.) На будущее: Сценарий использования плагина для платных пользователей 1. Чтобы воспользоваться мега-фичами для SEO-шников, вы решили стать платным пользователем. В качестве платного пользователя вы можете установить по плагину на все ваши говнозеркалки, научить их общаться друг с другом (автоматически проставлять ссылки друг на друга и пр.) и иными способами увеличивать визибилити, виральность, ретеншен и профит. 2. Вы регистрируетесь на сайте http://www.eventflow.ru и попадаете в свою Панель. В Панели вы сможете выбрать свой тарифный план, просмотреть состояние счета и историю списаний денежных средств, отчет об использовании квот, управлять токенами ваших приложений (экземпляров плагинов для WP и других приложений, которые мы вам предложим) и самими приложениями (активировать/деактивировать и пр.) 3. Вы устанавливаете плагин на свой WP. В процессе установки произойдет следующее: а) Плагин уже знает Consumer Key и Consumer Secret (зашито внутрь), эти параметры идентифицируют этот плагин как приложение, работающее с API (вид Eventflow API плагина вообще, возможно, его версию, но не конкретную его инсталляцию). б) Плагин обратится к Eventflow API по адресу https://api.eventflow.ru/oauth/request_token для получения Request Token (запрос на получение доступа). в) Плагин направит ваш браузер на вашу панель на сайте http://panel.eventflow.ru. Если вы не залогинены, вам придется войти в панель. г) В панели вы увидите страницу с просьбой подтвердить выдачу прав доступа для вашего плагина. Вы сможете подтвердить выдачу прав или отменить ее. д) После подтверждения вы будете снова направлены в админку вашего WP. Плагин запросит Access Token у Eventflow API, который будет ему выдан, т.к. вы разрешили. Это т.н. трехходовый OAuth, он требует участия пользователя. е) Плагин зафиксирует полученные Access Token и Access Secret в таблице в БД, в которой WP хранит настройки плагинов, и далее будет пользоваться ими для подписи всех дальнейших запросов к Eventflow API. Т.о. конкретный экземпляр плагина будет всегда однозначно идентифицироваться в рамках Eventflow API и вдобавок будет привязан к вашей учетной записи на Eventflow API. Для него будет осуществляться учет квот, тарификация и пр. Примечания: * Вы можете подключить много плагинов на разных сайтах. Все плагины, которые вы подключаете, будут связаны с вашей учетной записью. Квоты и тарификация будут производиться в зависимости от вашего тарифного плана. * При обновлении плагина (при появлении сообщения "Доступна новая версия плагина" в административном интерфейсе WP), процедура получения прав доступа к Eventflow API будет осуществлена автоматически. Будет автоматически осуществлено наследование квот и пр. Еще примеры приложение/виджетов Виджет "Тематический поток" для встраивания в сайты/новостные сайты/блоги или отдельно для смартфонов/телефонов. В настройках виджета (в панели на Eventflow API) можно указать интересующие темы, виджету будет передаваться curated content в real-time. (Типа новостные заголовки + блоги + twitter и пр.) ==================================== Информация для разработчиков ==================================== А. События, к которым привязаны обращения к Eventflow API 1. Первая активация плагина, POST в Request Token Endpoint, затем сразу POST в Access Token Endpoint 2. Создание записи (статус "скрыт"), POST в коллекцию, draft=yes 3. Обновление записи (публикация, редактирование или изменение статуса, перемещение в корзину), PUT, обновляем данные и ставим актуальное значение draft (yes для скрытой записи или записи в корзине, no для опубликованной) 4. Удаление навсегда (уничножение записи в БД), DELETE 5. Показ записи, Partial GET в ресурс (?fields=link) 6. (OPTIONAL) По крону, Partial GET в коллекцию (?fields=link), обновления для всех записей - **не реализовано** Б. Примеры запросов 1. Получение Request Token Запрос: POST http://api.eventflow.ru/oauth/request_token HTTP/1.1 Host: api.eventflow.ru Accept: */* Connection: Keep-Alive Authorization: OAuth oauth_version="1.0",oauth_nonce="db8426a63590705d346b465a817087a1",oauth_timestamp="1303479740",oauth_consumer_key="3c6e0b8a9c15224a8228b9a98ca1531d",oauth_token="",oauth_signature_method="HMAC-SHA1",oauth_signature="i9vBQ1eycHvJ72wx3FQhUn1FzNM%3D" Content-Type: application/x-www-form-urlencoded Content-Length: 0 Ответ: HTTP/1.1 200 OK Date: Fri, 22 Apr 2011 13:42:20 GMT Server: Apache/2.2.14 (Ubuntu) X-Powered-By: PHP/5.3.2-1ubuntu4.7 Vary: Accept-Encoding Content-Length: 96 Keep-Alive: timeout=15, max=100 Connection: Keep-Alive Content-Type: text/html oauth_token=89ebdf1f01efdde468743b3ab580c341&oauth_token_secret=0e2da26e2022d6989051c4999fb6310b 2. Получение Access Token Запрос: POST http://api.eventflow.ru/oauth/access_token HTTP/1.1 Host: api.eventflow.ru Accept: */* Connection: Keep-Alive Authorization: OAuth oauth_version="1.0",oauth_nonce="c40bb2577ad036fe4dee36c982145d4d",oauth_timestamp="1303479740",oauth_consumer_key="3c6e0b8a9c15224a8228b9a98ca1531d",oauth_token="89ebdf1f01efdde468743b3ab580c341",oauth_signature_method="HMAC-SHA1",oauth_signature="0WspiaQ2U%2F63Hcxgxi17W7EmN1M%3D" Content-Type: application/x-www-form-urlencoded Content-Length: 0 Ответ: HTTP/1.1 200 OK Date: Fri, 22 Apr 2011 13:42:20 GMT Server: Apache/2.2.14 (Ubuntu) X-Powered-By: PHP/5.3.2-1ubuntu4.7 Vary: Accept-Encoding Content-Length: 96 Keep-Alive: timeout=15, max=99 Connection: Keep-Alive Content-Type: text/html oauth_token=3617b24d8b3e714a68d7ffd21d5a703f&oauth_token_secret=9d9920be48181b9847656446471ccb5d 3. Создание записи Запрос: POST http://api.eventflow.ru/wordpress/post HTTP/1.1 Host: api.eventflow.ru Accept: */* Connection: Keep-Alive Authorization: OAuth oauth_version="1.0",oauth_nonce="22e9e074f4aaa85f84034e0557f95c23",oauth_timestamp="1303480953",oauth_consumer_key="3c6e0b8a9c15224a8228b9a98ca1531d",oauth_token="3617b24d8b3e714a68d7ffd21d5a703f",oauth_signature_method="HMAC-SHA1",oauth_signature="Ghm2KcA%2BFEY8HIEly5PpKfuubo4%3D" Content-Type: application/atom+xml;type=entry Content-Length: 382 Заголовок 2011-04-22T14:02:33+00:00 Новая запись 1 yes Ответ: HTTP/1.1 201 Created Date: Fri, 22 Apr 2011 14:02:33 GMT Server: Apache/2.2.14 (Ubuntu) X-Powered-By: PHP/5.3.2-1ubuntu4.7 X-RateLimit-Limit: 50 X-RateLimit-Remaining: 47 X-RateLimit-Reset: 1303502400 Location: http://api.eventflow.ru/wordpress/post/184 Content-Location: http://api.eventflow.ru/wordpress/post/184 Etag: "d2047cba0316ee12bfb0efb401c721fb" Content-Length: 504 Keep-Alive: timeout=15, max=100 Connection: Keep-Alive Content-Type: application/atom+xml;type=entry;encoding=UTF-8 Заголовок 2011-04-22T14:02:33+00:00 urn:uuid:6cdd60ea-0045-eb7a-6ec4-4c54d29ed402 Новая запись 1 yes 4. Обновление записи Запрос: POST http://api.eventflow.ru/wordpress/post/184 HTTP/1.1 Host: api.eventflow.ru Accept: */* Connection: Keep-Alive Authorization: OAuth oauth_version="1.0",oauth_nonce="69bf0ee444b50e4d64c2306918a7ac64",oauth_timestamp="1303480954",oauth_consumer_key="3c6e0b8a9c15224a8228b9a98ca1531d",oauth_token="3617b24d8b3e714a68d7ffd21d5a703f",oauth_signature_method="HMAC-SHA1",oauth_signature="WYBXynMyA%2FieJvJpZHTf4n76vQg%3D" X-Http-Method-Override: PUT If-Match: d2047cba0316ee12bfb0efb401c721fb Content-Type: application/atom+xml;type=entry Content-Length: 382 Заголовок 2011-04-22T14:02:33+00:00 Новая запись 1 no Ответ: HTTP/1.1 200 OK Date: Fri, 22 Apr 2011 14:02:34 GMT Server: Apache/2.2.14 (Ubuntu) X-Powered-By: PHP/5.3.2-1ubuntu4.7 Etag: "0d1bbcfa6d3892fb2785640189b13956" X-RateLimit-Limit: 50 X-RateLimit-Remaining: 47 X-RateLimit-Reset: 1303502400 Content-Length: 0 Keep-Alive: timeout=15, max=98 Connection: Keep-Alive Content-Type: application/xhtml;encoding=UTF-8 5. Удаление записи Запрос: POST http://api.eventflow.ru/wordpress/post/186 HTTP/1.1 Host: api.eventflow.ru Accept: */* Connection: Keep-Alive Authorization: OAuth oauth_version="1.0",oauth_nonce="f84d49218f445def7c605ce1fb49b0ea",oauth_timestamp="1303481485",oauth_consumer_key="3c6e0b8a9c15224a8228b9a98ca1531d",oauth_token="3617b24d8b3e714a68d7ffd21d5a703f",oauth_signature_method="HMAC-SHA1",oauth_signature="DC2gFNmtCvrWdmEPZU5HOvT6LdE%3D" X-Http-Method-Override: DELETE If-Match: 473e51966ba86a6d53bd9c9883fddcc5 Content-Length: 0 Content-Type: application/x-www-form-urlencoded Ответ: HTTP/1.1 200 OK Date: Fri, 22 Apr 2011 14:11:25 GMT Server: Apache/2.2.14 (Ubuntu) X-Powered-By: PHP/5.3.2-1ubuntu4.7 X-RateLimit-Limit: 50 X-RateLimit-Remaining: 47 X-RateLimit-Reset: 1303502400 Vary: Accept-Encoding Content-Length: 0 Keep-Alive: timeout=15, max=96 Connection: Keep-Alive Content-Type: text/html 6. Получение списка связанных записей Запрос: GET http://api.eventflow.ru/wordpress/post/183?fields=link&oauth_consumer_key=3c6e0b8a9c15224a8228b9a98ca1531d&oauth_nonce=3fc72066786bb3bf3739e5af1865bb2e&oauth_signature=ou2oCJW2S4H7G2XsE%2FkrD%2BOcnI8%3D&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1303479742&oauth_token=3617b24d8b3e714a68d7ffd21d5a703f&oauth_version=1.0 HTTP/1.1 Host: api.eventflow.ru Accept: */* Connection: Keep-Alive If-None-Match: da7c569cab46961d24d11fc6b1ed557b Ответ: HTTP/1.1 200 OK Date: Fri, 22 Apr 2011 15:47:42 GMT Server: Apache/2.2.14 (Ubuntu) X-Powered-By: PHP/5.3.2-1ubuntu4.7 X-RateLimit-Limit: 50 X-RateLimit-Remaining: 47 X-RateLimit-Reset: 1303502400 Etag: "24fed98296879e51f702a50534012125" Content-Length: 243 Keep-Alive: timeout=15, max=100 Connection: Keep-Alive Content-Type: application/atom+xml;type=entry;encoding=UTF-8 либо HTTP/1.1 304 Not Modified Date: Fri, 22 Apr 2011 15:45:36 GMT Server: Apache/2.2.14 (Ubuntu) Connection: Keep-Alive Keep-Alive: timeout=15, max=86 Vary: Accept-Encoding В. Виды ссылок в ответе на запрос получения списка связанных записей 1. Ссылка с rel="edit" соответствует ресурсу, создаваемому Eventflow API по запросу плагина, отправляемому методом POST по адресу коллекции. 2. Ссылка с rel="monitor" соответствует пермалинку поста, создаваемому Wordpress. Т.к. ссылка с rel="monitor" является частью ресурса в коллекции Eventflow API, она может быть модифицирована, напр., при изменении схемы URL администратором сайта на Wordpress. 3. Ссылка с rel="related" соответствует ресурсу, связанному с ресурсом по ссылке с rel="monitor". Связи устанавливаются в результате осуществления аналитической обработки ресурсов сервисом Eventflow и могут меняться с течением времени. Значения ссылок - URL сторонних ресурсов (они фигурируют в качестве link[@rel='monitor'] в других записях в коллекции Eventflow API, которые, однако, клиентам не доступны). Примечания: а) Отношение (relation) 'monitor' используется для ссылок на ресурсы, используемые для наблюдения за изменениями стороннего HTTP-ресурса (RFC5989). Мы, однако, в рамках своей системы, трактуем ссылку с rel="monitor" в качестве ссылки на сам HTTP-ресурс, представителем которого в коллекции Eventflow API является ресурс по ссылке с rel="edit". Иными словами, хотя RFC5989 предписывает трактовку данного отношения как "ресурс, осуществляющий наблюдение" (мониторящий), мы трактуем его как "ресурс под наблюдением" ("мониторимый"). б) Ответы сервера могут также содержать ссылки с другими значениями атрибута 'rel' в соответствии со спецификациями Atom Publishing Protocol (RFC5023) и Google Data ver. 2 в) Ссылки на скрытые ресурсы (для которых проставлен draft="yes") в выдаче не появляются.