+7 (499) 703-33-25

Документация по API

Оглавление

Общий обзор

Копини имеет API и механизм подписок на события сообщества. Обе части API оперируют одинаковыми форматами и служат одной цели - интеграция с другими системами с переносом туда данных из Копини и обработка их там.
Основное API Копини выполнено в стиле REST. Т.е. данные представляются как набор ресурсов, состояние которых можно изменять."

Точкой входа в API является http://api.copiny.com/ после которого идет адрес ресурса. Необходимые значения передаются нам как GET и POST параметры. Примеры вызова некоторых функций API можно просмотреть на странице примеров.

1 Адреса ресурсов

URL любого ресурса доступного через API имеет следующий вид:

            <id сообщества>/<ресурс>[/<id ресурса>][/подресурс[/<id подресурса>]][.<формат ответа(json|xml)>]
            
где

2 Параметры запроса

Требуемое действие

API Копини поддерживает 5 действий: index, get, post, put, delete. Для каждого ресурса имеется свой набор доступных действий.

Для GET-запросов используется действие index, в присутствии id ресурса - get.

Для POST запросов используемый метод может быть изменен присутсвием параметра _method (высший приоритет) либо http-заголовка X-HTTP-Method-Override. Если метод не изменен и должен использоваться POST, но присутсвует id ресурса, то будет использоваться PUT.

Действия имеют следующий смысл:

Подпись запроса

Каждый запрос должен быть подписан для подтверждения приложения отправившего его.

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

Формирование подписи запроса на PHP

            ksort($data);
            $sign = '';
            foreach ($data as $key =&gt; $value) {
                $sign .= ($key.'='.$value);
            }
            $sign .= $secret;
            $sign = md5($sign);
            

Полученная подпись указывается в параметре sig.

3 Формат ответа

В зависимости от указанного в запросе параметра <формат ответа> может выдаваться в формате 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"}]}

Объекты

topic - обсуждение

Данные об обсуждении. Есть два варианта. Полный формат отличается наличием данных об официальном ответе и подробным списком файлов в обсуждении. В кратком блоки 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:
{"topic":{"id":9523,"entity":"idea","community_id":"1","author":"3","title":"egsgseg","text":"esfefsefs","created":1323933184,"updated":1323933184,"status":{"code":"none","text":"\u043d\u0430 \u0440\u0430\u0441\u0441\u043c\u043e\u0442\u0440\u0435\u043d\u0438\u0438"},"rating":"0","answer_count":"0","flags":{"hidden":false,"files":true},"answer":{"text":"","created":0},"files":[{"id":"63","name":"1293183536_chilli.png","mime-type":"image\/png"},{"id":"64","name":"3768.pdf","mime-type":"application\/pdf"},{"id":"65","name":"Additional_Agreement_RUR.doc","mime-type":"application\/msword"},{"id":"66","name":"a_329779b9.jpg","mime-type":"image\/jpeg"},{"id":"67","name":"creators.csv","mime-type":"text\/csv"}]},"comments":[],"users":[{"id":"3","name":"\u041f\u0435\u0442\u044f \u0412\u0430\u0441\u0435\u0447\u043a\u0438\u043d","email":"awf@drhd.ru","phone":"584651651","avatar":"http:\/\/idea.test\/images\/user\/03\/3.jpg?1338808430","facebook":"100001514177083","twitter":"177659339","vkontakte":"907501","moimir":"9513728692408056490"}]}

comment - комментарий

Данные об комментарии: идентификатор, текст, дата создания, рейтинг, идентификатор автора.

В формате xml:

            <comment>
            <id>5</id>
            <text>ddd sgsg sg gse</text>
            <created>1279802845</created>
            <rating>6</rating>
            <author>1</author>
            </comment>
В формате json:
{"id":5,"text":"ddd sgsg sg gse","created":1279802845,"rating":"6","author":"1"}

user - пользователь

Данные об пользовале: идентификатор, имя, email, телефон, ссылка на аватар на копини, рейтинг, id вконтакте (необяхательный), id facebook (необяхательный).

В формате xml: <user> <id>3</id> <name><![CDATA[Петя Васечкин]]></name> <email><![CDATA[seriousdron@ybandex.ru]]></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":"seriousdron@ybandex.ru","phone":"","avatar":"http:\/\/idea.test\/images\/user\/03\/3.jpg?1301388177","rating":"46"}

4 Доступные ресурсы

topic - ресурс для получения списков обсуждений.

Действие index

Возвращает смешанный список обсуждений, отсортированный каким-либо образом

Параметры:

Возвращаемые данные:

question, idea, problem, praise - ресурс для работы с вопросами, идеями, проблемами, благодарностями соответсвенно

Действие index

Возвращает список вопросов, идей, проблем, благодарностей соответственно. Можно задать режим выборки свой для каждого вида обсуждений. На каждой странице выдается 10 обсуждений.

Параметры:

Возвращаемые данные:

Действие get

Возвращает подробное описание обсуждения и комментарии к нему

Параметры:

Возвращаемые данные:

Действие put

Изменение обсуждения. Можно изменить статус обсуждения и/или оставить официальный ответ.

Параметры:

Возвращаемые данные:

Подресурс comment - ресурс для работы с комментариями к вопросам, идеям, проблемам, благодарностям

Используется только как под ресурс ресурсов question, idea, problem, praise. Пример вызова: POST /1/idea/3/comment

Действие post

Создание комментария к обсуждению

Параметры:

Возвращаемые данные:

Ресурс user - получение списка участников сообщества

Действие index

Параметры: -нет-

Возвращаемые данные:

Действие get

Параметры:

Возвращаемые данные:

search - ресурс для проведения поиска в сообществе

Действие index

Возвращает смешанный список обсуждений, отсортированный по релевантности

Параметры:

Возвращаемые данные:

Ресурс file - получение содержимого файла

Действие get

Возвращает содержимое файла, залитого пользователем

Параметры:

Возвращаемые данные:

5. API подписок

Вы можете задать произвольный URL для вызовы сервером Копини при происхождени некоторого события. В случае наступления данного события - произойдеть POST запрос этот URL с сервера Копини. Объект из-за которого произошло данное событие будет передан в виде JSON в теле POST запроса.

Для получения тела POST-запроса в PHP используйте вызов функции file_get_contents('php://input').