Черновой вариант описания API проекта «Åвточмо».

Соответствует где-то версии 2.2 «Зачем».

Вступительное слово. Немного букв, все полезные.
Промышленный сервер autochmo.ru
Интерфейс API на промышленном сервере xml.autochmo.ru
Тестовый сервер avtochmo.greensight.ru
Интерфейс API тестового сервера xml-avtochmo.greensight.ru
Интерфейс API тестового сервера xml_avtochmo.greensight.ru

Формат XML ответа сервера

Валидный ответ сервера выглядит следующим образом:

<?xml version="1.0" encoding="UTF-8"?>
<autochmoreply>
        <requesttime> тут время запроса (таймстамп) </requesttime>
        <requestmethod> тут метод запроса (обычно GET или POST) </requestmethod>
        <replytime> тут время ответа сервера (таймстамп) </replytime>
        
        Тело ответа.
        
</autochmoreply>

Сервер принимает запросы и выдаёт ответы в кодировке UTF-8. Использование иной кодировки в запросе не запрещается, но и не гарантирует адекватные ответы.

Формат XML ошибок

В случае каких-либо проблем или ошибок, которые сервер может обработать, он отвечает XML с описанием ошибки. XML ошибки содержит внутри ответа элемент <error/>, у которого есть свойство code, а в себе он содержит текст ошибки. Например:

<?xml version="1.0" encoding="UTF-8"?>
<autochmoreply>
        <requesttime>1307535706</requesttime>
        <requestmethod>GET</requestmethod>
        <replytime>1307535707</replytime>
        <error code="NOT_IMPLEMENTED">Метод не реализован</error>
</autochmoreply>

Ниже представлен перечень кодов ошибок, которые сервер может возвращать:

NOT_IMPLEMENTED	Метод не реализован
NOT_FOUND	Запрашиваемый ресурс не найден
WRONG_CREDENTIALS	Неправильные логин и пароль
AUTHORIZATION_REQUIRED	Требуется авторизация
CANNOT_ADD_FACT	невозможно добавить факт
CANNOT_EDIT_FACT	Невозможно отредактировать факт

T B A

Формат предупреждений

Помимо ошибок, сервер может возвращать предупреждения. Тэг предупреждения имеет следующий формат:

<warning code="WARNING">Это предупреждение</warning>

Предупреждений может быть несколько, и они могут соседствовать с прочими элементами в ответе сервера. Предупреждения могут быть возвращены в ответах не на все запросы, а только на некоторые, и все возможные случаи описаны отдельно. Обрабатывать предупреждения или нет — дело разработчика приложения.

Возможные предупреждения, который может возвращать сервер: T B A

Авторизация

Авторизация осуществляется отправкой методом POST полей login и password по адресу authorize:

POST /authorize/
Поля POST:
{
        login: <логин пользователя>
        password: <пароль пользователя>
}

В случае, если логин и/или пароль неправильные, возвращается ошибка с кодом WRONG_CREDENTIALS. Если авторизация прошла успешно, будет возвращён набор данных порльзователя — его ID, ФИО и, самое главное, авторизационный хэш, который привязан к пользователю и который потом надо будет передавать серверу для подтверждения авторизованности пользователя при совершении действий, эту авторизованность требующих.

Пример ответа об успешной авторизации:

<?xml version="1.0" encoding="UTF-8"?>
<autochmoreply>
        <requesttime>1308213745</requesttime>
        <requestmethod>POST</requestmethod>
        <replytime>1308213746</replytime>
        <user id="1">
                <username full="1 3 2">
                        <name>1</name>
                        <secondname>2</secondname>
                        <lastname>3</lastname>
                </username>
                <passwordhash>&6thg^dsflo8<f6ewt3h4f384bdrtg5g3efev43</passwordhash>
        </user>
</autochmoreply>

Авторизация через OpenID/OAuth не реализована в данный момент. Кроме того, необходимо иметь в виду, что сессия ведётся средствами Битрикса, на котором работает весь сайт Авточмо, и поэтому обладает всеми сопутствующими достоинствами и недостатками. Кроме того, необходимо помнить о том, что символы < и >, которые могут попасться в хэше, заменены HTML-последовательностями < и > соответственно. Сессия хранится долго, то есть не слетает через некоторое время бездействия, однако, нельзя гарантировать то, что она будет храниться вечно. Если приложение не хранит у себя пароль пользователя, а хранит только возвращаемый при авторизации хэш, то, для заблаговременного сообщения пользователю о том, что его сессия истекла и ему необходимо ввести пароль снова, можно воспользоваться запросом CheckAuth. Он ничего не делает, только проверяет, может ли пользователь авторизоваться по указанному логину и хэшу пароля. Ну и продлевает сессию, наверное, тоже.

Проверка авторизации

Осуществляется отправкой запроса методом POST по адресу /checkauth/:

POST /checkauth/
Поля POST:
{
        login: <логин пользователя>
        passwordhash: <хэш пароля>
}

Ответ сервера стандарный, в теле ответа присутствует всего один элемент <checkauthresult>, который содержит строку либо «ok», либо «fail», и имеет свойство result, равное 1 или 0 соответственно.

Логаут

На всякий случай, мало ли, вдруг понадобится, сделана и возможность разлогинится. Запрос exit посылается методом POST или GET по адресу exit:

POST /exit/
GET /exit/

Никаких параметров более передавать не нужно. Тело ответа всегда будет сообщать об успешном завершении процедуры. Выглядит это так:

<?xml version="1.0" encoding="UTF-8"?>
<autochmoreply>
        <requesttime>1308220587</requesttime>
        <requestmethod>GET</requestmethod>
        <replytime>1308220588</replytime>
        <callresult result="1">ok</callresult>
</autochmoreply>

Факт

Факт — это описание случая авточмошничества. Содержит ссылки на фотографии, комментарий запостившего факт пользователя, государственный регистрационный номер или пометку «без номера» автомобиля, дату и координаты точки, и так далее.

Запрос факта осуществляется методом GET на адрес /<fact-id>:

GET /<fact-id>

Сервер либо возвращает ошибку NOT_FOUND, либо описание факта.

Описание факта:

<fact id="номер факта">
        <name> название случая. Поле не имеет никакого практического применения </name>
        <comment> комментарий случая </comment>
        <datecreated readable="дата создания в формате Y-m-d H:i:s"> таймстамп </datecreated>
        <gosnomer id="id госномера" type="тип номера" nomer="номер без региона" number="номер" series="серия" region="регион"> весь номер целиком </gosnomer>
        <latitude> широта </latitude>
        <longitude> долгота </longitude>
        <carmodel id="ид модели" manufacturer="марка"> модель </carmodel>
        <rating plus="рейтинг в поюс (оправдательный)" minus="рейтинг в минус (осудительный)"> суммарный рейтинг </rating>
        <commentsnum> количество комментариев </commentsnum>
        <video> количество приложенных к случаю видеофайлов </video>
        <videos> в том случае, если есть приложенные файлы, содержит информацию о них:
                <video>
                        <url> абсолютная ссылка на видеоролик </url>
                        <original> относительные ссылки на скриншоты разных размеров <original>
                        <medium> ... <medium>
                        <small> ... <small>
                        <tiny> ... <tiny>
                </video>
                ...
        </videos>
        <counts>
                <gosnomer> количество фактов с таким же госномером </gosnomer>
                <carmodel> количество фактов с такой же моделью </carmodel>
        </counts>
        Далее — картинки четырёх разных размеров.
        <pictures>
                <original>
                        <src> путь к картинке относительно корня сайта </src>
                        <src>...</src>
                        ...
                </original>
                <medium>
                        <src>...</src>
                        ...
                </medium>
                <small>
                        <src>...</src>
                        ...
                </small>
                <tiny>
                        <src>...</src>
                        ...
                </tiny>
        </pictures>
</fact>

При добавлении факта пользователь может ввести любой регистрационный номер, мы не ограничиваем пользователей шаблонами. В зависимости от того, каким образом сайт распознал введённый номер, элемент <gosnomer> может иметь разные значения, равно как и его свойства. Если тип номера не распознан, свойства тэга <gosnomer> не заполняются.

Типы регистрационных номеров, которые распознаёт сайт Авточмо:

Тип номера	Код (gosnomer type=)	Примечания
Обычный РФ	RUS
МВД (синий)	MVD
Дипломатический (красный)	DIP	Не имеет серии
Транзитный (жёлтый регион)	TRANS
Военный (чёрный)	MO
Вывозимое ТС (с буквой Т)	EXP
Общественный транспорт (жёлтый)	PUB

Список фактов

T B A

Список фактов получатся запросо методом GET по адресу /:

GET /

Дополнительно в качестве GET-параметров могут быть заданы условия фильтрации и сортировки.

Дополнительные GET-параметры.

gosnomer
carmnf
carmodel
gosnomer_type
DATE_FROM
DATE_TO
period_type
region
order
limit
offset
page

Формат ответа похож на формат ответа API РосЯмы со списком ям.

Список комментариев к факту

К каждому факту список комментариев можно получить отдельно запросом методом GET по адресу /<fact-id>/comments:

GET /<fact-id>/comments

В ответ вернётся список комментариев в XML. Формат тела ответа сервера:

<commentslist>
        <comment id="идентификатор комментария">
                <text> текст комментария </text>
                <username> имя пользователя </username>
                <usersecondname> фамилия пользователя </usersecondname>
                <userlastname> отчество пользователя </userlastname>
                <userlogin> поле не используется </userlogin>
                <datecreated readable="28.09.2011 22:59:47">1317236387</datecreated> - дата оставления комментария
                <entity> идентификатор комментируемой сущности </entity>
                <entitytype> идентификатор типа комментируемой сущности </entitytype>
        </comment>
        <comment> … </comment>
</commentslist>

Список комментариев сортируется по идентификатору (по времени оставления) по убыванию (более новые комментарии идут первыми). Ограничение на количество комментариев задать нельзя, все комментарии к факту выбираются сразу. Максимальное число комментариев, которое может быть возвращено, равно 10000. Элемент <entity> содержит в себе идентификатор сущности, к которой относится комментарий, элемент <entitytype> содержит в себе идентификатор типа комментируемой сущности.

Авточмо

Помимо факта, есть сущность «авточмо» или «госномер», представляющая из себя набор фактов, объединённых одним регистрационным государственным номером. Эта сущность также имеет рейтинг и комментарии, отдельные от рейтинга и комментариев фактов. Получить данные об авточме можно запросом GET по адресу /autochmo/<autochmo-id>:

GET /autochmo/<autochmo-id>

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

<commentslist>
        <comment id="ид комментария">
                <text> текст комментария </text>
                <username> имя пользователя </username>
                <usersecondname> фамилия пользователя </usersecondname>
                <userlastname> отчество пользователя </userlastname>
                <userlogin> поле не используется </userlogin>
                <datecreated readable="28.09.2011 22:59:47">1317236387</datecreated> - дата оставления комментария
        </comment>
        <comment> … </comment>
</commentslist>
<rating plus="положительная часть рейтинга (оправдано)" minus="отрицательная часть ерйтинга (осуждено)"> суммарный рейтинг </rating>
<factslist>
        <sort>
                <item code="ID">desc</item>
        </sort>
        <filter>
                <item code="gosnomer_id">686</item>
        </filter>
        <navigation></navigation>
        <factslist>
                Список фактов одного авточма имеет стандартную структуру списка фактов.
                <fact> … </fact>
                <fact> … </fact>
        </factslist>
</factslist>

Список авточмов

Список авточмов (по сути — список государствнных номеров, попавших на сайт Авточмо) можно получить запросом методом GET на адрес /autochmo:

GET /autochmo

Формат ответа сервера:

<autochmo id="идентификатор авточма"> государственный номер </autochmo>
<autochmo id="идентификатор авточма"> государственный номер </autochmo>
...

В том случае, если номер не определён, то текст государственного номера будет «no nomer». Список авточмов упорядочен по идентификатору по убыванию. Можно задать GET-параметры offset и limit для навигации по списку. Параметр limit означает количество элементов выборке, offset — отступ от начала списка до начала выборки. Пример:

GET /autochmo?limit=30&offset=90

Список комментариев к авточму

T B A

Парковка

T B A

Список парковок

T B A

Список комментариев к парковке

T B A

Список фактов пользователя

Пользователь может посмотреть список своих собственных фактов. Фильтрация общего списка фактов по загрузившему их пользоватею отсутствует по соображениям приватности, а для того, чтоб посмотреть список своих фактов, надо быть авторизованным. Список фактов, загруженных пользователем, может быть получен запросом методом POST по адресу /my/:

POST /my/
Поля POST
{
        login: <логин пользователя>
        passwordhash: <хэш пароля>
}

Поле passwordhash может быть заменено полем password, в котором передаётся не хэш пароля, а сам пароль пользователя. Список фактов, загруженных пользователем, сортируется и фильтруется аналогично общему списку фактов, и имеет точно такой же формат и структуру.

Список комментариев пользователя

Пользователь имеет возможность просмотреть список оставленных им комментариев к фактам. Функционал просмотра комментарии пользователя к иным видам сущностей (парковки, авточмы) пока не реализован. Для того, что получить список комментариев пользователя, надо отправить запрос методом POST на адрес /my/comments:

POST /my/comments
Поля POST
{
        login: <логин пользователя>
        passwordhash: <хэш пароля>
}

Поле passwordhash может быть заменено полем password, в котором передаётся не хэш пароля, а сам пароль пользователя. Список комментариев, оставленных пользователем, точно так же не фильтруется и не сортируется, как и список комментариев к факту, и все замечания относительно списка комментариев к факту относятся и к списку комментариев пользователя.

Элемент <entity> содержит в себе идентификатор сущности, к которой относится комментарий, элемент <entitytype> содержит в себе идентификатор типа комментируемой сущности. Более подробно — см. Добавление комментария.

Просмотр факта с точки зрения пользователя

T B A

POST /my/<fact-id>
Поля POST
{
        login: <логин пользователя>
        passwordhash: <хэш пароля>
}

Добавление факта

Небольшая путаница в терминологии.

Из-за сильного влияния внутренней терминологии разработчиков под «авточмом» может пониматься выложенный на сайт факт и одновоременно несколько фактов, объединённых одним регистрационным номером (все факты с участием данной машины). Во избежание путаницы авторы описания API всегда стараются уточнять, о факте или о группе фактов идёт речь, однако, если уточнения нет, то под «авточмом» следует понимать именно одиночный факт, если нет оснований полагать, что имеется в виду обратное.

Добавление авточма производится отправлением запроса методом POST на адрес /addfact/

POST /addfact/
Поля POST
{
T B A
        login
        password
        longitude
        latitude
        carmodel_id
        desc
        gosnomer
        nonomer
}

Описание полей POST.

login	Логин пользователя, под которым добавляется авточмо.
passwordhash	Хэш пароля пользователя, полученный при авторизации. Вместо поля passwordhash можно передавать пароль в поле password.
latitude, longitude	Соответственно широта и долгота случая в градусах (десятичная часть отделена от целой через точку). Вместо этих двух полей может быть передано одно поле coordinates, в котором широта и долгота передаются через запятую, либо поле coordinatesr, в котором они тоже передаются через запятую, но первой идёт долгота.
carmodel_id	Идентификатор модели (см. вызов соответствующего справочника).
carmodel	Строковое название модели. В том случае, если по какой-либо причине не передан параметр carmodel_id, то, ориентируясь по этой строке, сайт Авточмо сам попробует подобрать подходящую модель, или создаст новую. В том случае, если carmodel_id задан (и он не равен 0), параметр carmodel игнорируется.
desc	Описание авточма (комментарий).
gosnomer	Государственный номер в виде строки. Желательно передавать латинскими буквами и цифрами (например, o000oo00), однако, не обязательно — кириллические буквы тоже допустимы, однако, если в номере встретятся символы, не являющиеся цифрами и буквами латинского алфавита или кириллического алфавита, сходными по начертанию с латинскими, они будут удалены. Дописывать «RUS» после цифр региона не рекомендуется, так как тогда номер не будет распознан как валидный. Он будет добавлен, но тип его будет неопределён.
nogosnomer	Если этот параметр задан и не равен false, то будет добавлено авточмо без номера (с пометкой «номер не определён»). Возвращаемый результат представляет из себя либо ошибку, либо, в случае успешного добавления, тэг <callresult>, у которого имеется дополнительное свойство insertedfactid, значение которого равно идентификатору только что добавленного авточма.

Пример ответа при успешном добавлении авточма:

<autochmoreply>
        <requesttime>1316974835</requesttime>
        <requestmethod>POST</requestmethod>
        <replytime>1316974835</replytime>
        <callresult result="1" insertedfactid="686">ok</callresult>
</autochmoreply>

T B A

Получение справочника моделей автомашин

Запрос справояника требует авторизации, POST /getcarmodels

T B A

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

Запрос справочиника требует авторизации, POST /getcarmarks

T B A

Редактирование факта

T B A

POST /my/<fact-id>/update
Поля POST
{
        login: <��������������������������������������������������������������������������������������������������������������������������������������������������

��ение факта

T B A

POST /my/<fact-id>/delete
Поля POST
{
        login: <������������������������������

��авление комментария

Добавление комментария происходит с помощью отпраления вызова методом POST по адресу /addcomment:

POST /addcomment
Поля POST:
{
        login: < логин пользователя >
        passwordhash: < хэш пароля пользователя >
        entity_type_id: < идентификатор типа комментируемой сущности >
        entity_id: < идентификатор сущности >
        fact_id: < идентификатор факта >
        autochmo_id: < идентификатор авточма >
        parking_id: < идентификатор парковки >
        text: < текст комментария >
}

Для оставления комментария необходима авторизация. Вместо поля passwordhash можно передавать пароль пользователя.

Так как комментировать можно несколько разных типов сущностей, то, помимо идентификатора самой сущности (её id), необходимо указать и тип комментируемой сущности, так как, по понятной причине, у двух разных сущностей разных типов могут быть одинаковые идентификаторы. Указание типа комментируемой сущности может производиться двумя способами. Во-первых, можно указать явно entity_type_id.

Список идентификаторов типов комментируемых сущностей:

1	факты
2	парковки
3	авточмы

В случае, если указан идентификатор несуществующего типа, будет возвращена ошибка UNKNOWN_ENTITY_TYPE. Второй способ задания типа комментируемой сущности — с помощью иных параметров, передаваемых в POST, для удобства пользования. Вместо двух параметров entity_type_id и entity_id можно указать параметр fact_id (идентификатор комментируемого факта) или parking_id (идентификатор комментируемой парковки) или autochmo_id (идентификатор комментируемого авточма). Рекомендуем этот способ. Если не указан ни один из параметров, специфицирующих тип и идентификатор, будет возвращена ошибка ENTITY_TYPE_NOT_SPECIFIED, если будет укзаан тип, но указан идентификатор комментируемой сущности, будет возвращена ошибка ENTUTY_NOT_SPECIFIED. При попытке прокомментировать несуществующую сущность будет выдана ошибка NO_ENTITY.

Если текст комментярия пуст или состоит только из пробелов, будет возвращена ошибка NO_TEXT. Во избежание злоупотреблений текст обрезается по длине 10000 символов.

В результат выполнения запроса возвращается XML, содержащий элемент <callresult>, свойство insertedcommentid которого равно идентификатору добавленного комментария. Пример ответа о благополучном оставлении комментария:

<callresult result="1" insertedcommentid="247">ok</callresult>

Если что-то пошло не так и комментарий не добавился по какой-то причине, результат будет выглядеть так:

<callresult result="0">fail</callresult>

Добавление комментария к факту

T B A

Добавление комментария к чму

T B A

Добавление комментария к парковке

T B A

Голосование

Голосование происходит отправкой запроса методом POST по адресу /vote:

POST /vote
Поля POST:
{
        login: < логин пользователя >
        passwordhash: < хэш пароля пользователя >
        entity_type_id: < идентификатор типа комментируемой сущности >
        entity_id: < идентификатор сущности >
        fact_id: < идентификатор факта >
        autochmo_id: < идентификатор авточма >
        parking_id: < идентификатор парковки >
        comment_id: < идентификатор комментария >
        vote: 1|-1
}

Для голосвания необходима авторизация. Вместо поля passwordhash можно передавать пароль пользователя.

Так как голосовать можно за несколько разных типов сущностей, то, помимо идентификатора самой сущности (её id), необходимо указать и тип сущности, за которую идёт голосование, так как у двух разных сущностей разных типов могут быть одинаковые идентификаторы. Указание типа сущности может производиться двумя способами. Во-первых, можно указать явно entity_type_id.

Список идентификаторов типов сущностей, за которые можно голосовать.

1	avtochmo	факт
2	comments	комментарий
3	parking	парковка
4	gosnomer	госномер (авточмо)

Кроме того, можно (это рекомендуемый способ, так что даже лучше) передавать вместо entity_type_id и entity_id поля fact_id (идентификатор факта) или parking_id (идентификатор парковки) или autochmo_id (идентификатор авточма) или comment_id (идентификатор комментария).

Если не указан ни один из параметров, специфицирующих тип и идентификатор, будет возвращена ошибка ENTITY_TYPE_NOT_SPECIFIED, если будет укзаан тип, но указан идентификатор комментируемой сущности, будет возвращена ошибка ENTUTY_NOT_SPECIFIED. При попытке прокомментировать несуществующую сущность будет выдана ошибка NO_ENTITY.

Если не указано поле vote или оно равно нулю, то будет выведена ошибка NO_VOTE. Голосовать за свои комментарии нельзя, при попытке проголосовать за свой комментарий будет выведена ошабка UNAPPROPRIATE_METHOD. Голосовать за свои факты и парковки можно (пока ещё). Если за данную сущность голос уже отдан, будет возвращена ошибка NO_MORE_VOTES.

В случае успешного голосования будет возвращён в теле ответа сервера элемент <callresult> со значением ok и свойством result, равным 1, а если голос не был добавлен, то элемент <callresult> будет иметь значение fail, а его свойство result будет равно 0.

Голосование за факт

T B A

Голосование за чмо

T B A

Голосование за парковку

T B A

Голосование за комментарий

T B A

Геокодирование

Прямое геокодирование — определение координат по топониму. Обратное — наоборот. Для уменьшения злоупотребления геокодированием авторизация пользователя является обязательной. Фактически, геокодер Авточма является прокси-сервером для геокодера Яндекса, так что можно обращаться напрямую в Яндекс, и ответ сервера практически совпадает с ответом Яндекса:

http://api.yandex.ru/maps/geocoder/doc/desc/concepts/About.xml

Геокодирование получается обращением методом POST по адресу /geocode/:

POST /geocode/
Поля POST:
{
        login: <логин пользователя>
        passwordhash: <хэш пароля>
        geocode: <любая строка или координаты через запятую>
}

Вместо passwordhash может быть передан password. Обратите внимание, что в поле geocode передаётся сначала долгота, потом широта.

Ответ сервера содержит в себе элемент <geocode>, в котором целиком содержится (за исключением тэга <?xml>) ответ Яндекса в формате XML (пробелы, которыми сделан отступ строк слева, заменены на символы табуляции). В случае ошибки элемент <geocode> отсутствует, а вместо него выводится ошибка. Если не указан адрес или координаты, то выводится ошибка GEOCODE_EMPTY_REQUEST (пустой запрос к геокодеру), в случае каких-либо иных ошибок выводится GEOCODE_ERROR.

Черновой вариант описания API проекта «Åвточмо».

Формат XML ответа сервера

Формат XML ошибок

Формат предупреждений

Авторизация

Проверка авторизации

Логаут

Факт

Список фактов

Список комментариев к факту

Авточмо

Список авточмов

Список комментариев к авточму

Парковка

Список парковок

Список комментариев к парковке

Список фактов пользователя

Список комментариев пользователя

Просмотр факта с точки зрения пользователя

Добавление факта

Получение справочника моделей автомашин

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

Редактирование факта

����ение факта

��авление комментария

Добавление комментария к факту

Добавление комментария к чму

Добавление комментария к парковке

Голосование

Голосование за факт

Голосование за чмо

Голосование за парковку

Голосование за комментарий

Геокодирование

��ение факта