Копини имеет API и механизм подписок на события сообщества. Обе части API оперируют одинаковыми форматами и служат одной цели - интеграция с другими системами с переносом туда данных из Копини и обработка их там.
Основное API Копини выполнено в стиле REST. Т.е. данные представляются как набор ресурсов, состояние которых можно изменять."
Точкой входа в API является http://api.copiny.com/ после которого идет адрес ресурса. Необходимые значения передаются нам как GET и POST параметры. Примеры вызова некоторых функций API можно просмотреть на странице примеров.
URL любого ресурса доступного через API имеет следующий вид:
<id сообщества>/<ресурс>[/<id ресурса>][/подресурс[/<id подресурса>]][.<формат ответа(json|xml)>]где
API Копини поддерживает 5 действий: index, get, post, put, delete. Для каждого ресурса имеется свой набор доступных действий.
Для GET-запросов используется действие index, в присутствии id ресурса - get.
Для POST запросов используемый метод может быть изменен присутсвием параметра _method (высший приоритет) либо http-заголовка X-HTTP-Method-Override. Если метод не изменен и должен использоваться POST, но присутсвует id ресурса, то будет использоваться PUT.
Действия имеют следующий смысл:
Каждый запрос должен быть подписан для подтверждения приложения отправившего его.
При использовании данного вида подписи приложение будет выполнять действия от лица создателя сообщества. Т.е. автором комментариев и официальных ответов будет создатель сообщества.
ksort($data); $sign = ''; foreach ($data as $key => $value) { $sign .= ($key.'='.$value); } $sign .= $secret; $sign = md5($sign);
Полученная подпись указывается в параметре sig.
В зависимости от указанного в запросе параметра <формат ответа> может выдаваться в формате xml или json, при этом структура и набор данных не меняется.
В формате xml все строковые поля с содержимым отличающимся от безопасного набора символов из английский букв, основных знаков препинания и пробела взяты в блоки CDATA.
Все значения даты и времени представляются в формате Unix-timestamp.
Если запрос был некорректен или в процессе его выполнения произошла ошибка, то корневой элемент ответа будет называться errors и он будет содержать 1 или более элементов типа error. Элемент типа error может включать в себя поля code - код ошибки и message - сообщение об ошибке для логгирования.
Пример ответа с ошибкой в формате xml:
<?xml version="1.0" encoding="utf-8"?> <errors><error><code>1</code><message>Приложение не найдено</message></error></errors>
Пример ответа с ошибкой в формате json:
{"errors":[{"code":1,"message":"\u041f\u0440\u0438\u043b\u043e\u0436\u0435\u043d\u0438\u0435 \u043d\u0435 \u043d\u0430\u0439\u0434\u0435\u043d\u043e"}]}
Данные об обсуждении. Есть два варианта. Полный формат отличается наличием данных об официальном ответе и подробным списком файлов в обсуждении. В кратком блоки answer и files отсутствует.
Поля: идентификатор, тип обсуждения, заголовок, текст (м.б. пустым), дата создания, дата последнего обновления, блок статус (код и текст для пользователя), рейтинг, количество ответов (включая оф. ответ), флаги (скрытое обсуждение, прикреплены файлы), блок официального ответа (текст, ид автора, дата создания).
Коды статусов. Для всех видов обсуждений присутсвует код со статусом none. Это начальный статус, для благодарностей (entity=praise) он же единственный. Список кодов статусов:
Для вопросов:
Формат описания файла
В формате xml:
<topic> <id>3</id> <entity>idea</entity> <author>1</author> <title><![CDATA[Предлагаю идею]]></title> <text><![CDATA[Шоб все работало!]]></text> <created>1279194347</created> <updated>1316595357</updated> <status> <code>reject</code> <text><![CDATA[отклонена]]></text> </status> <rating>23</rating> <answer_count>14</answer_count> <flags> <hidden/> <files>1</files> </flags> <answer> <text><![CDATA[редактирование!]]></text> <author>1</author> <created>1316516038</created> </answer> <files> <file> <id>64</id> <name><![CDATA[ 3768.pdf ]]></name> <mime-type><![CDATA[ application/pdf ]]></mime-type> </file> <file> <id>65</id> <name><![CDATA[ Additional_Agreement_RUR.doc ]]></name> <mime-type><![CDATA[ application/msword ]]></mime-type> </file> </files> </topic>В формате json:
Данные об комментарии: идентификатор, текст, дата создания, рейтинг, идентификатор автора.
В формате xml:
<comment> <id>5</id> <text>ddd sgsg sg gse</text> <created>1279802845</created> <rating>6</rating> <author>1</author> </comment>В формате json:
Данные об пользовале: идентификатор, имя, email, телефон, ссылка на аватар на копини, рейтинг, id вконтакте (необяхательный), id facebook (необяхательный).
В формате xml: <user>
<id>3</id>
<name><![CDATA[Петя Васечкин]]></name>
<email><![CDATA[[email protected]]]></email>
<phone></phone>
<avatar><![CDATA[http://idea.test/images/user/03/3.jpg?1301388177]]></avatar>
<rating>46</rating>
</user>
В формате json:
{"id":"3","name":"\u041f\u0435\u0442\u044f \u0412\u0430\u0441\u0435\u0447\u043a\u0438\u043d","email":"[email protected]","phone":"","avatar":"http:\/\/idea.test\/images\/user\/03\/3.jpg?1301388177","rating":"46"}
Возвращает смешанный список обсуждений, отсортированный каким-либо образом
Параметры:
Возвращаемые данные:
Возвращает список вопросов, идей, проблем, благодарностей соответственно. Можно задать режим выборки свой для каждого вида обсуждений. На каждой странице выдается 10 обсуждений.
Параметры:
Возвращаемые данные:
Возвращает подробное описание обсуждения и комментарии к нему
Параметры:
Возвращаемые данные:
Изменение обсуждения. Можно изменить статус обсуждения и/или оставить официальный ответ.
Параметры:
Возвращаемые данные:
Используется только как под ресурс ресурсов question, idea, problem, praise. Пример вызова: POST /1/idea/3/comment
Создание комментария к обсуждению
Параметры:
Возвращаемые данные:
Параметры: -нет-
Возвращаемые данные:
Параметры:
Возвращаемые данные:
Возвращает смешанный список обсуждений, отсортированный по релевантности
Параметры:
Возвращаемые данные:
Возвращает содержимое файла, залитого пользователем
Параметры:
Вы можете задать произвольный URL для вызовы сервером Копини при происхождени некоторого события. В случае наступления данного события - произойдеть POST запрос этот URL с сервера Копини. Объект из-за которого произошло данное событие будет передан в виде JSON в теле POST запроса.
Для получения тела POST-запроса в PHP используйте вызов функции file_get_contents('php://input').