Информация для разработчиков
В этом документе содержится информация о методах общения с сервером iMGSRC.RU из сторонних приложений, основное предназначение которых мы видим в быстром размещении большого количества фотографий на сайте. Впервые протокол был использован в официальном клиенте iMGSRC.RU, программе для массовой загрузки фото на сервер -
Скачай и посмотри, как просто написать программу для массовой загрузки фото!
Если у тебя есть знания в любом языке программирования, то ты можешь помочь общему делу развития iMGSRC.RU, получить много благодарностей и опыта. Если всего этого тебе покажется мало, мы можем даже заплатить денег :) Пиши нам - мы ответим на все вопросы!
1. Авторизация, получение списка альбомов пользователя
Информация об альбомах пользователя доступна по URL
http://imgsrc.ru/cli/info.php?login=login&passwd=password
здесь и далее login - логин пользователя, а password - MD5-hash пароля пользователя. Задание пароля в виде хеша решает сразу две проблемы. Во-первых пароль не "светится" при передаче по открытым сетям и во-вторых его можно сразу хранить в таком виде в системном реестре, что делает его менее уязвимым.
В ответ на запрос возвращается XML-ответ (существует ли пользователь, правильный ли пароль) и список альбомов, в случае успешной авторизации:
<?xml version="1.0" encoding="windows-1251"?>
<!DOCTYPE info PUBLIC "-//imgsrc.ru//DTD INFO 1.0//EN" "http://imgsrc.ru/cli/info.dtd">
<info proto="0.8"> <-- Версия протокола iMGSRC.RU -->
<status>OK</status> <-- Статус запроса: OK - пароль и логин верны. NOK - произошла ошибка, описание в <error> -->
<store>0<store> <-- Номер сервера, на котором размещается пользователь. Используется далее при загрузке фотографий -->
<error>no error. login ok, album data follows</error> <-- Варианты: 'incorrect password or username', 'unknown database error' -->
<albums> <-- Начало списка альбомов -->
<album id="179"> <-- ID альбома в БД iMGSRC.RU -->
<name>AKVA</name> <-- Название альбома -->
<photos>26</photos> <-- Количество фото в альбоме -->
<modified>2006-04-03 22:45:53</modified> <-- Дата последнего изменения альбома -->
</album> <-- конец описания альбома с ID=179 -->
<album id="180">
<name>ANTON</name>
<photos>26</photos>
<modified>2005-12-16 17:31:03</modified>
</album>
... подобная же схема для других альбомов
<album id="181">
<name>APELSIN</name>
<photos>60</photos>
<modified>2005-12-16 17:31:21</modified>
</albums> <-- Конец списка альбомов -->
</info> <-- Конец XML ответа -->
2. Список разделов iMGSRC.RU
Список разделов доступен по URL
http://imgsrc.ru/cli/cats.php
Список не нуждается в сортировке.
<?xml version="1.0" encoding="windows-1251" ?>
<!DOCTYPE info PUBLIC "-//imgsrc.ru//DTD INFO 1.0//EN" "http://imgsrc.ru/cli/info.dtd">
<info proto="0.8">
<status>OK</status>
<error>no error. categories follow</error>
<categories>
<category id="4"> <-- ID раздела -->
<name>авто-мото</name> <-- название раздела -->
<parent_id>0</parent_id> <-- ID родительского раздела или 0, если раздел является "верхним" -->
</category>
<category id="5">
<name>тюнинг</name>
<parent_id>4</parent_id>
</category>
...
</categories>
</info>
3. Создание альбома
Запрос для создания альбома совпадает с запросом информации о существующих альбомах за исключением того, что в передаваемых параметрах добавляется название нового альбома:
http://imgsrc.ru/cli/info.php?login=login&passwd=password&create=название+альбома[&create_passwd=пароль+для+создаваемого+альбома]
[&create_category=id_категории]
Пароль [параметр create_passwd=] задавать необязательно, в случае если он будет пустой или параметр будет опущен, создается альбом без пароля.
Список доступных категорий доступен в XML-виде здесь.
Причин по которой альбом может не создаться всего две - неправильный пароль и ошибка соединения с базой (<status>NOK</status> в XML ответе).
4. Размещение файлов
В случае корректной авторизации (<status>OK</status> в XML ответе), дальше можно размещать фотографии. Файлы посылаются методом POST c обязательным указанием логина и пароля в том же виде, что и в первом запросе, на URL (store - номер сервера, полученный в ответе на запрос 1)
http://estore.imgsrc.ru/cli/post.php?login=login&passwd=password&album_id=album_id
что аналогично исполнению формы, примерно такого содержания: <form method=post enctype='multipart/form-data' action=/cli/post.php?login=login&passwd=password&album_id=album_id>
1: <input type=file name=u1><br>
2: <input type=file name=u2><br>
3: <input type=file name=u3><br>
4: <input type=file name=u4><br>
5: <input type=file name=u5><br>
<input type=submit>
</form>
album_id - ID альбома, полученного в первом или втором запросе. Количество посылаемы файлов таким образом не ограничено, однако на плохих линках лучше посылать файлы по одному, чтобы не попасть в ситуацию обрыва связи в середине запроса.
Также стоит уменьшать фотографии до 800 точек по горизонтали при 85% JPEG сжатии на стороне клиента и только после этого пересылать на сервер.
В случае пересылки файлов большего геометрического размера они все равно будут уменьшены, но пользователь потратит больше времени на загрузку, что нерационально.
Также не принимаются файлы размером больше 3Мб.
Примерный ответ сервера на POST зпрос будет следующим:
<?xml version="1.0" encoding="windows-1251"?>
<!DOCTYPE info PUBLIC "-//imgsrc.ru//DTD INFO 1.0//EN" "http://imgsrc.ru/cli/info.dtd">
<info proto="0.8"> <-- Версия протокола iMGSRC.RU -->
<status>OK</status> <-- Статус запроса: OK - пароль и логин верны. NOK - произошла ошибка, описание в <error> -->
<error>no error. login ok, album data follows</error> <-- Варианты: 'incorrect password or username', 'unknown database error' -->
<error>no error. files posted ok, urls following</error>
<uploads count="1"> <-- Начало списка загруженных фото и их количество -->
<photo id="116775"> <-- Новый ID загруженного фото -->
<page>http://imgsrc.ru/test/116775.html</page> <-- Ссылка на страницу фотографии -->
<small>http://s0.imgsrc.ru/t/test/116775.jpg</small> <-- Ссылка на уменьшенную копию изображения -->
<big>http://b0.imgsrc.ru/t/test/116775eiv.jpg</big> <-- Ссылка на большую версию картинки -->
</photo> <-- Конец описания загруженной фотографии -->
</uploads> <-- Конец списка загруженных фото -->
</info> <-- Конец ответа -->
Количество принятых фото (<uploads count="1"> в XML ответе) может не совпадать с количеством отправленных файлов по разным причинам, включая обрыв связи в процессе пересылки, неверный формат файла и тп.
5. Версии, контакты и пр
Описываемая версия протокола - 0.8
История версий:
2008-06-06. Версия протокола 0.8
- Добавлен номер сервера в ответ на запрос авторизации, необходим для корректной работы загрузки на зеркала.
2006-05-05. Версия протокола 0.7
- Добавлена возможность задания категории альбома при создании.
2006-05-03. Версия протокола 0.6
- Добавлена возможность создания альбомов с паролем.
2006-04-11. Версия протокола 0.5
- Первая публичная версия.
Комментарии и предложения можно (и нужно :) отправлять по адресу skinny.bravo@gmail.com.
|