воскресенье, 14 августа 2011 г.

РосЯма API 1.4 upd1

API РосЯмы


Соответствует текущей версии 1.4 РосЯмы.
Общение с сервером РосЯмы любое внешнее приложение осуществляет посредством запроса к серверу по протоколу http (а лучше — https, но сейчас это ещё не реализовано) на определённый адрес. Сервер в ответ присылает XML.
Запросы могут быть посланы как методом GET, так и методом POST, в зависимости от запроса. В случае, если приложение отправляет запрос методом GET, то может передать какие-нибудь данные в строке URL, а также в строке URL содержится тип запроса. Проще говоря, в зависимости от того, что приложение хочет получить и сообщить, оно формирует запрос на определённый URL. Запросы методом POST используются для отправки на сервер больших объёмов информации (загрузка картинок и так далее), а также могут быть использованы для выполнения запросов, которые требуют авторизации. Все запросы, для которых авторизация не требуется, отправляются на сервер методом GET.
Промышленный сервер, который принимает запросы: http://xml.rosyama.ru/.
Тестовый сервер, на котором можно отлаживать приложения: http://xml_st1234.greensight.ru или http://xml-st1234.greensight.ru. Веб-интерфейс тестового сервера: http://st1234.greensight.ru.
Следует помнить, что тестовый сервер обычно имеет более свежую версию исходного кода и может работать (что обычно и происходит) менее стабильно, чем промышленный, так как изменения происходят там в непрерывном режиме, а на промышленный сервер переносятся пачками время от времени. Текущая версия API на промышленном сервере описана по адресу http://rosyama.ru/api/, на тестовом сервере по адресу http://st1234.greensight.ru/api/.

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


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

	Тело ответа.
	

</st1234reply>


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


В случае каких-либо проблем или ошибок, которые сервер может обработать, он отвечает XML с описанием ошибки. XML ошибки содержит внутри ответа элемент <error/> (это единственный элемент тела ответа), у которого есть свойство code, а в себе он содержит текст ошибки. Например:
<?xml version="1.0" encoding="UTF-8"?>
<st1234reply>
	<requesttime>1307535706</requesttime>
	<requestmethod>GET</requestmethod>
	<replytime>1307535707</replytime>
	<error code="NOT_IMPLEMENTED">Метод не реализован</error>
</st1234reply>

Ниже представлен перечень кодов ошибок, которые сервер может возвращать:
NOT_IMPLEMENTEDМетод не реализован
NOT_FOUNDЗапрашиваемый ресурс не найден
NO_FILESНе загружено ни одного файла
TOO_BIG_FILEСлишком большой файл
TOO_MANY_FILESСлишком много файлов
PARTIALLY_UPLOADED_FILEФайл загружен только частично
CANNOT_UPLOAD_FILEНевозможно загрузить файл
UNKNOWN_MIME_TYPEНеподдерживаемый тип файла
UNKNOWN_IMAGE_FORMATНеподдерживаемый формат изображения
INCORRECT_TYPEНеправильный тип дефекта
DEPRECATED_TYPEНеиспользуемый в данный момент тип дефекта
CANNOT_ADD_DEFECTНевозможно добавить дефект
AUTHORIZATION_REQUIREDТребуется авторизация
LATITUDE_NOT_SETНе указана широта дефекта
LONGITUDE_NOT_SETНе указана долгота дефекта
NO_ADDRESSНе указан адрес
WRONG_CREDENTIALSНеправильный логин и/или пароль
UNAPPROPRIATE_METHODНеподходящий метод
CANNOT_UPDATE_DEFECTНе удалось обновить дефект
CANNOT_DELETE_DEFECTНе удалось удалить дефект
GEOCODE_ERRORНе удалось произвести геокодирование
GEOCODE_EMPTY_REQUESTПустой запрос к геокодеру
INTERNALИная внутренняя ошибка

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


Помимо ошибок, сервер может возвращать предупреждения. Тэг предупреждения имеет следующий формат:
<warning code="WARNING">Это предупреждение</warning>

Предупреждений может быть несколько, и они могут соседствовать с прочими элементами в ответе сервера. Предупреждения могут быть возвращены в ответах не на все запросы, а только на некоторые, и все возможные случаи описаны отдельно. Обрабатывать предупреждения или нет — дело разработчика приложения.
Возможные предупреждения, который может возвращать сервер:
FILES_DROPPEDНесколько файлов не загружено на сервер
CANNOT_REALISE_SUBJECTRFНе удалось распознать субъект РФ
CANNOT_REALISE_CITYНе удалось распознать город
FILES_LIMIT_REACHEDДостигнуто максимальное количество файлов для одного дефекта
NO_SUBJECTRF_IDДефект не привязан к субъекту РФ


Формат XML описания дефекта


В разных запросах могут приходить описания разных дефектов. В списке дефектов их несколько, в карточке дефекта — он, соответственно, один. Во всех случаях XML с описанием дефекта выглядит одинаково.
<hole id="номер дефекта">
	<id> номер дефекта </id>
	<username full="полоное имя пользователя">
		<name>имя</name>
		<secondname>отчество</secondname>
		<lastname>фамилия</lastname>
	</username>
	<latitude> широта </latitude>
	<longitude> долгота </longitude>
	<address city="название города" subjectrf="идентификатор субъекта РФ">полный адрес дефекта</address>
	<state code="код статуса дефекта">русское название статуса</state>
	<type code="код типа дефекта">русское название типа</type>
	<datecreated readable="02.06.2011">1307003591</datecreated> - дата создания дефекта
	<datesent readable="02.06.2011">1307003789</datesent> - дата отправки заявления в ГИБДД
	<datestatus readable="02.06.2011">1307003797</datestatus> - дата простановки текущего статуса
	<commentfresh>комментарий пользователя к дефекту</commentfresh>
	<commentfixed>комментарий, который пользователь оставляет при отметке дефекта, как починенного</commentfixed>
	<commentgibddre>комментарий, который пользователь оставляет при простановке статуса «пришёл ответ из ГИБДД»</commentgibddre>
	<pictures>
		<original> - картинки оригинального размера (ну на самом деле не оригинального,
а ужатого до 1024 пикселей по ширине для экономии места на сервере)
			<fresh> - картинки к «свежему» дефекту, загружаемые на сайт при добавлении дефекта.
Этот элемент (равно как и соседние с ним <gibddreply> и <fixed>)
может иметь внутри любое (в том числе и нулевое) количество элементов <src>,
в которых содержатся пути к картинкам дефектов относительно корня http-сервера (обычного, где крутится сайт)
				<src>src</src>
				<src>src</src>
				...
			</fresh>
			<gibddreply>...</gibddreply>
			<fixed>...</fixed>
		</original>
		<medium> - картинки среднего размера, которые показываются на сайте внутри карточки дефекта
			<fresh>...</fresh>
			<gibddreply>...</gibddreply>
			<fixed>...</fixed>
		</medium>
		<small> - картинки маленького размера
			<fresh>...</fresh>
			<gibddreply>...</gibddreply>
			<fixed>...</fixed>
		</small>
	</pictures>
</hole>

Список дефектов


Список дефектов получается простым запросом к корню http-сервера методом GET. Могут быть переданы параметры, влияющие на фильтрацию, возможно, упорядочивание и отображение списка дефектов. Например:
GET /?filter_rf_subject_id=77&filter_type=holeonroad&filter_status=fixed

Приведённый запрос отфильтрует выведет дефекты, расположенные в регионе 77, типа «яма на дороге» и в статусе «починенные». Просто запрос «GET / » выведет все ямы. Список дефектов можно получать без авторизации.
Возможные параметры, которые могут быть переданы в запросе:
filter_rf_subject_idИдентификатор субъекта РФ, к которому относится дефект. Нумерация субъектов не совпадает с нумерацией регионов ГИБДД а совпадает, скорее, с порядком, в котором перечислены субъекты РФ в статье Википедии про субъекты РФ. Пронумерованный список субъектов можно получить с сервера, отправив ему запрос GetRegions (об этом ниже). Если передать номер несуществующего региона, то дефекты выбраны не будут, результат запроса будет пустым. Однако, если передать ноль или какую-нибудь белиберду, которая превратится в ноль после приведения типов, то будут выбраны дефекты, у которых не определён субъект РФ (такие на самом деле имеются, они возникают из-за сбоев при геокодировании, но их мало).
Соответствует имени поля ADR_SUBJECTRF.
filter_cityФильтр по названию города (или по его началу). Если указать, например, «Волг», то будут выбраны ямы, расположенные в Волгограде, Волгодонске и во прочих всех городах, название которых начинается на «Волг».
Соответствует имени поля ADR_CITY.
filter_statusФильтр по статусам дефектов. Может принимать значения:
  • fresh — свежий дефект, только добавлен на сайт;
  • inprogress — в процессе, заявление в ГИБДД;
  • fixed — отремонтирован;
  • achtung — просрочен (прошло более 37 дней с момента подачи заявления в ГИБДД, никакого результата не видно);
  • prosecutor — отправлена жалоба в прокуратуру на бездействие органов ГИБДД;
  • gibddre — получен ответ из ГИБДД, но дефект не отремонтирован.
Если передать несуществующий статус, то дефекты выбраны не будут.
Соответствует имени поля STATE.
filter_type
Фильтр по типу дефектов. Спектр типов дефектов довольно обширен, часть типов не используется на сайте, хотя предусмотрены:
  • badroad — разбитая дорога;
  • holeonroad — яма на дороге;
  • hatch — люк;
  • crossing — переезд (не используется);
  • nomarking — отсутствие разметки (не используется);
  • rails — рельсы;
  • policeman — лежачий полицейский;
  • fence — ограждение (не используется);
  • holeinyard — яма во дворе;
  • light — неисправный светофор (не используется).
Если передать несуществуюший тип, то дефекты выбраны не будут.
Соответствует имени поля TYPE.
limitКоличество возвращаемых дефектов. Если не указано, то берётся по умолчанию, 30 штук. На всякий случай максимальный лимит ограничен 2000 дефектами, чтоб злоумышленники не принялись выбирать дефекты десятками тысяч, положив БД и забив канал.
offsetЕсли надо выбрать некоторое количество дефектов не с первого, то можно использовать offset — количество дефектов между первым по порядку и первым возвращённым в выборке. Если не указано, то считается равным 0.
page
Этот параметр обладает более высоким приоритетом по сравнению с limit и offset, если указать его, то limit и offset будут проигнорированы. Смысл его в том, что он переопределяет эти параметры следующим образом:
limit = default_limit (30 дефектов),

offset = page*default_limit.
То есть нумерация страниц начинается с ноля.
orderЗадумано как изменение порядка дефектов в возвращаемом списке, но пока не реализовано и игнорируется.
htmlЕсли этот параметр присутствует, то вместо XML возвратится HTML — вёрстка списка дефектов, рассчитанная на маленький (смартфонный) экран. Но пока что не реализовано и игнорируется.

Формат возвращаемого в ответе XML.
Основная информация содержится в элементе <defectslist> в теле ответа. Там перечислены элементы <hole> - дефекты, полученные в этой выборке. Формат каждого элемента <hole> описан выше. Тело ответа, помимо присутствующих всегда элементов, содержит некоторые дополнительные:
<st1234reply>
	...
	<sort> - тут описана сортировка выбоки. В каждом элементе <item>, которых может быть любое количество,
но обычно только один, указано направление сортировки,
а в свойстве code — имя поля, по которому идёт сортировка.
		<item code="ID">desc</item>
		...
	</sort>
	<filter> - тут описана фильтрация. При применении фильтров (см. таблицу выше)
здесь содержатся элементы <item>, значение которых — значение фильтра, а свойство code — имя поля,
по которому производится фильтрация, которое не совпадает с названием фильтра (опять же см. таблицу выше).
		<item code="ADR_CITY">Москва</item>
		...
	</filter>
	<navigation> - параметры выборки из БД, limit и offset.
		<item code="limit">30</item>
		<item code="offset">0</item>
	</navigation>
	<defectslist>
		<hole ...>...</hole>
		<hole ...>...</hole>
		<hole ...>...</hole>
		…
	</defectslist>

Карточка дефекта


Карточка дефекта является общедоступной информацией, для просмотра не требуется авторизация. Чтоб получить XML с карточкой дефекта, надо отправить запрос методом GET на адрес вида /<id дефекта>, например: GET /123 — получить дефект с номером 123 (GET /123/ - тоже, слэш на конце не влияет на номер).
Если такой дефект существует, то он будет возвращён в XML в теле ответа в описанном выше формате. В том случае, если он существует, но не прошёл премодерацию, будет возвращена ошибка NOT_FOUND.

Запрос GetRegions


Служебный запрос GetRegions возвращает список регионов, про которые знает РосЯма, с их названиями и внутренней нумерацией. Так как эта нумерация по понятной причине не совпадает с ГИБДД-шной, то этот запрос будет полезен для того, чтоб посмотреть, какой номер у такого-то региона или какой регион с таким-то номером. Под «регионом» понимается полноценный субъект РФ. Запрос GetRegions не имеет никаких параметров фильтрации. Отправил запрос — получил список регионов, всё. Авторизация тоже не нужна для этого.
Запрос:
GET /getregions

Формат тела ответа:
<regionslist>
	<region id=" номер региона ">полное название</region>
	...
</regionslist>

Пример ответа:
<?xml version="1.0" encoding="UTF-8"?>
<st1234reply>
	<requesttime>1307688681</requesttime>
	<requestmethod>GET</requestmethod>
	<replytime>1307688681</replytime>
	<regionslist>
		<region id="1">Республика Адыгея</region>
		<region id="2">Республика Алтай</region>
		<region id="3">Республика Башкортостан</region>
		<region id="4">Республика Бурятия</region>
		<region id="5">Республика Дагестан</region>
		<region id="6">Республика Ингушетия</region>
		<region id="7">Кабардино-Балкарская республика</region>
		…
	</regionslist>
</st1234reply>

Авторизация

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

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

В случае, если логин и/или пароль неправильные, возвращается ошибка с кодом WRONG_CREDENTIALS. Если авторизация прошла успешно, будет возвращён набор данных порльзователя — его ID, ФИО и, самое главное, авторизационный хэш, который привязан к пользователю и который потом надо будет передавать серверу для подтверждения авторизованности пользователя при совершении действий, эту авторизованность требующих.
Пример ответа об успешной авторизации:
<?xml version="1.0" encoding="UTF-8"?>
<st1234reply>
	<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>
</st1234reply>

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

Запрос CheckAuth


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

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

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

Запрос exit


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

GET /exit/

Никаких параметров более передавать не нужно. Тело ответа всегда будет сообщать об успешном завершении процедуры. Выглядит это так:
<?xml version="1.0" encoding="UTF-8"?>
<st1234reply>
	<requesttime>1308220587</requesttime>
	<requestmethod>GET</requestmethod>
	<replytime>1308220588</replytime>
	<callresult result="1">ok</callresult>
</st1234reply>

Список дефектов, выложенных на сайт пользователем


Список дефектов, которые выложил на сайт определённый пользователь получается запросом методом POST по адресу /my/:
POST /my/

Поля POST:
{
	login: <логин пользователя>
	passwordhash: <хэш пароля, полученный при авторизации>
}

Вместо поля passwordhash может быть передан собственно пароль в поле password (тогда поле passwordhash должно отсутствовать вообще, а не быть нулевой длины). В том случае, если логин и хэш пароля (пароль) принадлежат одному пользователю, то в ответе содержится список дефектов, выложенных на сайт этим пользователем, в том числе и те, которые ещё не прошли премодерацию. В противном случае ответ будет содержать ошибку AUTHORIZATION_REQUIRED.
К списку собственных дефектов может быть применён фильтр, аналогичный фильтру обычного списка дефектов, и выглядит он точно так же.

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


Авторизованный пользователь может смотреть информацию по каждому из загруженных им дефектов, даже по тем, которые ещё не прошли премодерацию. Для этого надо отправить запрос методом POST по адресу /my/xxx/, где xxx — номер дефекта, который пользователь хочет посмотреть. Например:
POST /my/154/

Поля POST:
{
	login: <логин пользователя>
	passwordhash: <хэш пароля, полученный при авторизации>
}

Вместо поля passwordhash может быть передан собственно пароль в поле password (тогда поле passwordhash должно отсутствовать вообще, а не быть нулевой длины). В том случае, если логин и хэш пароля (пароль) принадлежат пользователю, загрузившему на сайт указанный дефект (в примере — дефект №154), то будет возвращено описание запрошенного дефекта. Если логин и хэш пароля (пароль) не принадлежат одному пользователю, будет возвращена ошибка AUTHORIZATION_REQUIRED, а если дефект принадлежит другому пользователю, то будет возвращена ошибка NOT_FOUND.

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


Добавление дефекта осуществляется отправкой необходимых данных методом POST по адресу /add/.
POST /add/

Поля POST:
{
	login: <логин пользователя>
	passwordhash: <хэш пароля>
	address: <адрес ямы, желательно в формате xAL>
	latitude: <широта дефекта>
	longitude: <долгота дефекта>
	comment: <комментарий пользователя к дефекту>
	type: <тип дефекта>
}

Кроме того, должен быть передан хотя бы один графический файл с фотографией ямы.
Комментарии к передаваемым полям POST:
passwordhashСодержит хэш пароля. Вместо этого поля можно передать пароль в поле password, но тогда поле passwordhash должно отсутствовать (а не быть равным пустой строке).
loginЛогин пользователя. В том случае, если логин и пароль (хэш пароля) не соответствуют одному пользователю, будет возвращена ошибка AUTHORIZATION_REQUIRED.
addressАдрес должен быть в формате xAL, или, по крайней мере, начинаться как адрес в этом формате. Определение текстового поля «название города» и числового «идентификатор субъекта РФ» происходит именно на основании данных адреса. Поэтому хорошей практикой может считаться определение адреса по координатам с помощью обратного геокодирования, и позволение пользователю дописать что-то в конец адреса, или слегка отредактировать первую часть адреса, но тогда не исключена такая ситуация, что дефект, территориально расположенный в городе N, будет не находиться в этом городе при поиске по названию города N. Адрес является обязательным параметром, при его отсутствии будет возвращена ошибка NO_ADDRESS.
В случае, если по адресу не удалось определить субъект РФ, в XML будет отдельное поле с предупреждением:
<warning code="CANNOT_REALISE_SUBJECTRF">Не удалось опередить субъект РФ</warning>
А если не удалось опередить город, то аналогичное предупреждение CANNOT_REALISE_CITY.
latitude, longitudeШирота и долгота месторасположения дефекта. Их можно не передавать по отдельности, а передать сразу в поле coordinates перечисленными через запятую, сначала широта, потом долгота. Либо передать их в поле coordinatesr через запятую, но сначала долгота, а потом широта. Координаты должны быть переданы, это обязательные параметры. В том случае, если они не будут переданы, будут возвращены ошибки LATITUDE_NOT_SET или LONGITUDE_NOT_SET.
commentТекстовый комментарий к дефекту, может быть пустым.
typeТип дефекта, один из возможных. При указании несуществующего типа будет возвращена ошибка INCORRECT_TYPE, при указании существующего, но неиспользуемого типа дефектов будет возвращена ошибка DEPRECATED_TYPE.

Комментарии к файлам.
Файлы должны быть переданы именно как файлы (encryption type должно быть «multipart/form-data»). Имена, под которыми файлы передаются на сервер, не имеют значения, но их должно быть не больше десяти. Обрабатываться они будут в том порядке, в котором будут переданы на сервер. В том случае, если файлов будет больше, чем десять, те файлы, которые были переданы после десятого, не будут обработаны, и будет выдано предупреждение FILES_DROPPED.
В том случае, если суммарный размер файлов превышает допустимые ограничения, никакой специфической ошибки не возвращается, так как веб-сервер обычно обрабатывает эту ситуацию самостоятельно. Вероятнее всего в этом случае можно получить ошибку AUTHORIZATION_REQUIRED. Узнать максимальный размер одного файла и максимальный суммарный размер файлов можно с помощью запроса GetFileUploadLimits.
В случае, если при загрузке файлов произошли какие-то другие ошибки, то они будут выведены в XML.
Ошибки, которые могут возникнуть при загрузке файлов:
NO_FILESНи одного файла не загружено
TOO_BIG_FILEСлишком большой файл
TOO_MANY_FILESСлишком много файлов (количество превышает директиву max_file_uploads в php.ini) — но эту ошибку вряд ли можно наблюдать, если честно
PARTIALLY_UPLOADED_FILEФайл загружен только частично
CANNOT_UPLOAD_FILEНевозможно загрузить файл.
Это сообщение выдаётся в случае, если загрузить файлы не удалось по какой-то внутренней причине, о которой пользователю знать не обязательно — проблемы с записью на диск, с правами доступа и так далее.
UNKNOWN_MIME_TYPEНеподдерживаемый формат файла.
В качестве изображений принимаются картинки форматов JPEG, PNG и GIF, попытка загрузить файл любого другого формата вызовет эту ошибку.
UNKNOWN_IMAGE_FORMATНеизвестный формат изображения.
Если mime-type и содержимое картинки не совпадают или что-то случилось на сервере, что не позволяет открыть этот файл для пережатия в меньший размер, то будет показана эта ошибка.

В том случае, если по какой-то причине не удалось добавить дефект, то будет возвращена ошибка CANNOT_ADD_DEFECT, в которой будет описание, почему, собственно, не удалось добавить дефект, и элемент callresult с результатом 0 (fail). В том случае, если дефект добавить удалось, будет возвращён его идентификатор в элементе XML-репорте об успешном завершении операции:
<callresult result="1" inserteddefectid="32">ok</callresult>

В свойстве inserteddefectid элемента callresult находится идентификатор добавленного дефекта.

Запрос GetFileUploadLimits


Запрос позволяет выяснить настройки PHP на сервере и прочие ограничения, присутствующие при загрузке фалов на сервер. Отправляется методом GET по адресу /getfileuploadlimits:
GET /getfileuploadlimits

Запрос авторизации не требует и возвращает вот такой XML:
<?xml version="1.0" encoding="UTF-8"?> 
<st1234reply> 
	<requesttime>1308920653</requesttime> 
	<requestmethod>GET</requestmethod> 
	<replytime>1308920653</replytime> 
	<maxpostsize>1M</maxpostsize> 
	<maxfilesize>3M</maxfilesize> 
	<maxfilescount>10</maxfilescount> 
</st1234reply>

Элементы <maxpostsize> и <maxfilesize> содержат значения значений post_max_size и upload_max_filesize из php.ini в том виде, в каком они содержатся там; как видно в примере — даже без проверок на адекватность. Элемент maxfilescount содержит максимальное число файлов, которое можно загрузить за один раз.

Изменение дефекта


Существует несколько запросов, позволяющих изменить дефект. Эти запросы различны по тем данным, которые могут быть изменены, и по тому, когда они могут быть вызваны, это зависит от статуса дефекта. По своей сути эти запросы сводятся к одному универсальному, но снаружи этого не видно.
Список запросов, которыми можно изменять дефект.
ЗапросСтатус дефекта, когда может быть вызван запросПоля, которые можно изменять, и прочие допустимые изменения
updateновыйкоординаты, тип, строка адреса, комментарий, можно загружать ещё файлы и удалять имеющиеся
set_inprogressновый, исправленоменяется статус на «в процессе». Для дефекта в статусе «исправлено» этот запрос доступен только в том случае, если не была загружена фотография исправленного дефекта, и статус может измениться на «просрочен» или «получен ответ из гибдд», в зависимости от того, какой был статус до статуса «исправлен»
revokeв процессеменяется статус обратно на «новый»
set_repliedв процессеменяется статус на «получен ответ из ГИБДД», необходимо добавить одно или несколько изображений (обычно скан ответа из ГИБДД) и, по желанию, комментарий
set_fixedвсе, кроме «новый» и «исправлено»меняется статус на «исправлено», можно добавить одно или несколько изображений и комментарий
to_prosecutorпросроченстатус меняется на «жалоба в прокуратуру подана»
revoke_pжалоба в прокуратуру поданастатус меняется обратно на «просрочен»

Дефект переходит из статуса «в процессе» в статус «просрочен» самостоятельно с течением времени.
Для удобства пользования существует служебный запрос GetUpdateMethods, который сообщает список возможных способов изменить дефект, а также — какие поля принимаются при каждом запросе.

Вызов GetUpdateMethods


Вызов существует в двух вариантах — в общем случае и применительно к дефекту. В общем случае вызывается методом GET адрес /getupdatemethods:
GET /getupdatemethods

Применительно к одному дефекту он вызывается методом POST по адресу /my/<defect_id>/getupdatemethods:
POST /my/<defect_id>/getupdatemethods

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

Как и в других случах, тут вместо хэша пароля можно передать собственно пароль в поле password, а поле passwordhash в таком случае должно отсутствовать. В том случае, если логин и пароль не подходят, будет выдана ошибка AUTHORIZATION_REQUIRED. В том счлкчае, если дефект с номером <defect_id> отсутствует или загружен другим пользователем, будет выдана ошибка NOT_FOUND.
В общем случае тело ответа сервера выглядит следующим образом:
<state id="state-id">
	<method name="method-name"> 
		<field>field_name</field>
		...
	</method>
	... 
</state>
…

В теле ответа перечислены элементы state (теоретически, их может и не быть), каждый из которых соответствует статусу дефекта. В случае, если вы запрашиваете этот метод для одного дефекта, то элемент state будет максимум один — соответствующий статусу выбранного дефекта. У элемента state есть свойство id — это код статуса дефекта.
Внутри элемента state расположены элементы method, каждый из которых соответствует методу обновления дефекта, который может быть вызван для дефекта в текущем статусе. Соответственно, этих элементов тоже может не быть. У элемента method есть свойство name, которое является именем этого метода.
Внутри элемента method расположены элементы field (их тоже может не быть), каждый из которых соответствует свойству дефекта, который может быть изменён данным методом. И является ключом массива с данными, который передаётся методом POST при обновлении дефекта. Более подробно о кодах field см. в описании метода обновления update.

Метод обновления дефекта update


Это наиболее полный метод обновления дефекта, с помощью которого данные дефекта можно обновить полностью (за исключением авторства и даты создания, разумеется). Поэтому данный метод применим только к дефектам в статусе «новый».
Вызывается данный метод отправкой данных методом POST на адрес /my/<defect-id>/update:
POST /my/<defect-id>/update

Поля POST (практически идентичны с методом добавления дефекта):
{
	login: <логин пользователя>
	passwordhash: <хэш пароля>
	address: <адрес ямы, желательно в формате xAL>
	latitude: <широта дефекта>
	longitude: <долгота дефекта>
	comment: <комментарий пользователя к дефекту>
	type: <тип дефекта>
	deletefiles: <удаляемые файлы>
}

Кроме того, могут быть переданы графические файлы, который добавятся к дефекту.
Комментарии к передаваемым полям POST:
passwordhashСодержит хэш пароля. Вместо этого поля можно передать пароль в поле password, но тогда поле passwordhash должно отсутствовать (а не быть равным пустой строке).
loginЛогин пользователя. В том случае, если логин и пароль (хэш пароля) не соответствуют одному пользователю, будет возвращена ошибка AUTHORIZATION_REQUIRED.
addressАдрес должен быть в формате xAL, или, по крайней мере, начинаться как адрес в этом формате. Если адрес не передан, то адрес дефекта не изменится. В случае, если по адресу не удалось определить субъект РФ, в XML будет отдельное поле с предупреждением:
<warning code="CANNOT_REALISE_SUBJECTRF">Не удалось опередить субъект РФ</warning>
А если не удалось опередить город, то аналогичное предупреждение CANNOT_REALISE_CITY.
latitude, longitudeШирота и долгота месторасположения дефекта. Их можно не передавать по отдельности, а передать сразу в поле coordinates перечисленными через запятую, сначала широта, потом долгота. Либо передать их в поле coordinatesr через запятую, но сначала долгота, а потом широта.
Если координаты не переданы, то координаты дефекта не изменятся.
commentТекстовый комментарий к дефекту, может быть пустым. Если не передан, то не комментарий к дефекту не изменится.
typeТип дефекта, один из возможных. При указании несуществующего типа будет возвращена ошибка INCORRECT_TYPE, при указании существующего, но неиспользуемого типа дефектов будет возвращена ошибка DEPRECATED_TYPE. Если тип не передан, то тип дефекта не изменится.
deletefilesМассив либо строка с перечисленными через запятую файлами, которые надо удалить (например, «1.jpg, 2.jpg»).

Комментарии к загружаемым файлам аналогичны случаю создания дефекта. С помощью многократного редактирования дефекта можно загрузить достаточно большое количество файлов, но их суммарное количество не должно превышать 100, в противном случае будут выведены предупреждения FILES_DROPPED и FILES_LIMIT_REACHED (достигнуто максимальное количество файлов для дефекта).
В том случае, если данный метод неприменим для дефекта из-за того, что последний не в статусе «новый», будет выведена ошибка UNAPPROPRIATE_METHOD (неподходящий метод).
Если обновление дефекта прошло успешно, то будет выведен элемент <callresult result="1">ok</callresult>, в противном случае будет выведен элемент <callresult result="0">fail</callresult> и ошибка CANNOT_UPDATE_DEFECT (не удалось обновить дефект) в том случае, если произошёл какой-то сбой иного рода, элемент error будет содержать текст ошибки, например:
<error code="CANNOT_UPDATE_DEFECT">Неподдерживаемый формат изображения</error>


Метод обновления дефекта set_inprogress


Метод предназначен, в основном, для перевода дефекта из статуса «новый» в статус «в процессе», однако, может применяться и для отмены статуса «исправлен» в том случае, если ещё не была загружена фотография исправленного дефекта. Вызывается отправкой запроса методом POST на адрес /my/<defect-id>/setinprogress:
POST /my/<defect-id>/setinpgogress

Поля POST:

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

Вместо passwordhash может быть передан password.
В том случае, если метод неприменим, будет выведена ошибка UNAPPROPRIATE_METHOD. Результат выполнения выводится в элементе <callresult>. Если произошла какая-то иная ошибка, то будет выведена ошибка CANNOT_UPDATE_DEFECT, элемент error будет содержать текст ошибки.

Метод обновления дефекта revoke


Метод служит для возвращения дефекту, который в статусе «в процессе», статуса «новый». Соответственно, применим только для дефектов в статусе «в процессе». Вызывается отправкой запроса методом POST по адресу /my/<defect-id>/revoke:
POST /my/<defect-id>/revoke

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

Вместо passwordhash может быть передан password.
В том случае, если метод неприменим, будет выведена ошибка UNAPPROPRIATE_METHOD. Результат выполнения выводится в элементе <callresult>. Если произошла какая-то иная ошибка, то будет выведена ошибка CANNOT_UPDATE_DEFECT, элемент error будет содержать текст ошибки.

Метод обновления дефекта set_replied


Данный метод предназначен для перевода дефекта из статуса «в процессе» в статус «получен ответ из ГИБДД». Применим только к дефектам в статусе «в процессе». Вызывается отправкой запроса методом POST по адресу /my/<defect-id>/setreplied:
POST /my/<defect-id>/setreplied

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

Вместо passwordhash может быть передан password.
Должен быть передан как минимум один графический файл, являющийся, по замыслу, сканом ответа из ГИБДД. Максимальное число файлов всё так же 10. Комментарий не обязателен.
В том случае, если метод неприменим, будет выведена ошибка UNAPPROPRIATE_METHOD. Результат выполнения выводится в элементе <callresult>. Если произошла какая-то иная ошибка, то будет выведена ошибка CANNOT_UPDATE_DEFECT, элемент error будет содержать текст ошибки. Если не загружено ни одного файла, будет выдана ошибка NO_FILES. Также могут быть выданы ошибки, связанные с загрузкой файлов, аналогичные описанным в разделе о методе обновления update.

Метод обновления дефекта set_fixed


Данный метод предназначен для перевода дефекта в статус «исправлено». Применим к дефекту в любом статусе, кроме «новый» и «исправлено». Вызывается отправкой запроса методом POST по адресу /my/<defect-id>/setfixed:
POST /my/<defect-id>/setfixed

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

Вместо passwordhash может быть передан password.
Комментарий не обязателен. Также могут быть переданы графические файлы, но они тоже не обязательны, и к ним относятся все замечания, касающиеся загрузки файлов, для вышеописанных методов.
Следует отметить отдельно, что в том случае, если файл не был загружен, то дефект можно вернуть в статус «в процессе» (или «просрочен»), а если был загружен файл, то нельзя.
В том случае, если метод неприменим, будет выведена ошибка UNAPPROPRIATE_METHOD. Результат выполнения выводится в элементе <callresult>. Если произошла какая-то иная ошибка, то будет выведена ошибка CANNOT_UPDATE_DEFECT, элемент error будет содержать текст ошибки. Если не загружено ни одного файла, будет выдана ошибка NO_FILES. Также могут быть выданы ошибки, связанные с загрузкой файлов, аналогичные описанным в разделе о методе обновления update.

Метод обновления дефекта to_prosecutor


Метод служит для простановки дефекту статуса «заявление отправлено в прокуратуру». Метод применим только для просроченных дефектов (находящихся в статусе «просрочен»). Вызывается отправкой запроса методом POST по адресу /my/<defect-id>/toprosecutor:
POST /my/<defect-id>/toprosecutor

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

Вместо passwordhash может быть передан password.
В том случае, если метод неприменим, будет выведена ошибка UNAPPROPRIATE_METHOD. Результат выполнения выводится в элементе <callresult>. Если произошла какая-то иная ошибка, то будет выведена ошибка CANNOT_UPDATE_DEFECT, элемент error будет содержать текст ошибки.

Метод обновления дефекта revoke_p


Метод служит для простановки дефекту в статуске «заявление в прокуратуре» статуса «просрочен». Вызывается отправкой запроса методом POST по адресу /my/<defect-id>/revokep:
POST /my/<defect-id>/revokep

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

Вместо passwordhash может быть передан password.
В том случае, если метод неприменим, будет выведена ошибка UNAPPROPRIATE_METHOD. Результат выполнения выводится в элементе <callresult>. Если произошла какая-то иная ошибка, то будет выведена ошибка CANNOT_UPDATE_DEFECT, элемент error будет содержать текст ошибки.

Удаление дефекта


Удалить можно только дефект в статусе «новый». Для этого надо отправить запрос методом POST по адресу /my/<defect-id>/delete:
POST /my/<defect-id>/delete

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

Вместо passwordhash может быть передан password.
В том случае, если метод неприменим, будет выведена ошибка UNAPPROPRIATE_METHOD. Результат выполнения выводится в элементе <callresult>. Если произошла какая-то иная ошибка, то будет выведена ошибка CANNOT_DELETE_DEFECT, элемент error будет содержать текст ошибки.

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


Прямое геокодирование — определение координат по топониму. Обратное — наоборот. Для уменьшения злоупотребления геокодированием авторизация пользователя является обязательной. Фактически, геокодер РосЯмы является прокси-сервером для геокодера Яндекса, так что можно обращаться напрямую в Яндекс, и ответ сервера практически совпадает с ответом Яндекса: 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.

Получение ФИО начальника ГИБДД региона


Для того, чтоб узнать ФИО начальника УГИБДД региона, в котором расположен дефект, необходимо воспользоваться запросом getgibddhead. Запрос выполняется методом POST по адресу /my/<defect-id>/getgibddhead, и для него необходима авторизация:
POST /my/<defect-id>/getgibddhead/

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

Вместо passwordhash может быть передан password.
Ответ сервера содержит элемент <gibddhead>, в котором три элемента - <nominative> и <dative> - соответственно, ФИО начальника УГИБДД соответствующего региона в именительном (nominative) и дательном (dative) падежах. Каждый из этих элементов имеет свойство post, значение которого — пост, занимаемый указанным начальником. Элемент <gibddhead>, помимо этого, имеет свойство subjectid, в котором содержится внутренний ID субъекта РФ. Кроме того, элемент <nominative> имеет свойство gibdd, содержащее наименование управления в именительном падеже.
Пример тела ответа сервера:
<gibddhead subjectid="72"> 
	<nominative
post="Начальник УПРАВЛЕНИЯ ГИБДД УВД СМОЛЕНСКОЙ ОБЛАСТИ"
gibdd="УПРАВЛЕНИЕ ГИБДД УВД СМОЛЕНСКОЙ ОБЛАСТИ">Ивченков Владимир Владимирович</nominative> 
	<dative post="Начальнику УПРАВЛЕНИЯ ГИБДД УВД СМОЛЕНСКОЙ ОБЛАСТИ">Ивченкову Владимиру Владимировичу</dative> 
</gibddhead>

Если дефекта не существует или он принадлежит другому пользователю, будет выведена ошибка NOT_FOUND. В случае, если что-то пошло не так, будет выведена ошибка INTERNAL (внутренняя ошибка). Если дефект не привязан к региону, то ошибки не будет, а все эти значения будут пустыми, но будет дополнительно выведено предупреждение NO_SUBJECTRF_ID (дефект не привязан к субъекту РФ).
Несколько замечаний. Список началников ГИБДД по регионам с периодом примерно раз в неделю автоматически обновляется с сайта gibdd.ru. Если на сайте gibdd.ru поменяется вёрстка, то, разумеется, обновление поломается. Переделывание именительного падежа в родительный происходит через API склонятора Яндекса http://nano.yandex.ru/project/inflect/.

Получение с сервера PDF


В некоторых ситуациях вместо ответа в формате XML сервер может предложить для скачивания PDF-файл со сформированным заявлением в прокуратуру или жалобой в ГИБДД. Для получения с сервера PDF необходимо отправить запрос методом POST по определённому адресу и передать заполненные поля, которые подставятся в текст.

Формирование и получение с сервера жалобы в ГИБДД


Для получения с сервера жалобы в ГИБДД в формате PDF необходимо отправить на сервер запрос методом POST по адресу /my/<defect-id>/pdf_gibdd/:
POST /my/<defect-id>/pdf_gibdd/

Поля POST:
{
	login: <логин пользователя>
	passwordhash: <хэш пароля>
	to: <кому>
	from: <от кого>
	postaddress: <почтовый адрес отправителя>
	holeaddress: <адрес дефекта>
	signature: <подпись (фамилия и инициалы отправителя)>
}

Вместо passwordhash может быть передан password.
В поле from должно быть указано полное имя отправителя. Так как на сайте в профиле может быть не указано полное правильное имя пользователя, имеется возможность указать его отдельно. В поле to должно быть написана должность и полное имя сотрудника ГИБДД, которому адресуется жалоба. Должность и полное имя сразу в дательном падеже начальника управления ГИБДД соответствующего субъекта РФ можно получить с помощью запроса getgibddhead. Так как ответы из ГИБДД будут приходить в письменной форме почтой, необходимо указать свой почтовый адрес. На сайте не хранятся почтовые адреса пользователей. Адрес дефекта нужно указать чётко, чтоб было понятно в ГИБДД.
Данный запрос применим только к дефектам, находящимся в статусах «новый» и «в процессе». В случае, если дефект находится не в этих статусах, будет выведена ошибка UNAPPROPRIATE_METHOD. Скрипты на сайте не проверяют валидность вводимых данных. Сгенерированный PDF-файл не хранится на сервере.

Формирование и получение с сервера заявления в прокуратуру


Для получения с сервера жалобы в ГИБДД в формате PDF необходимо отправить на сервер запрос методом POST по адресу /my/<defect-id>/pdf_prosecutor/:
POST /my/<defect-id>/pdf_prosecutor/

Поля POST:
{
	login: <логин пользователя>
	passwordhash: <хэш пароля>
	from: <от кого>
	postaddress: <почтовый адрес отправителя>
	holeaddress: <адрес дефекта>
	signature: <подпись (фамилия и инициалы отправителя)>
	gibdd: <название отделения ГИБДД>
	gibddre: <ответ ГИБДД>
}

Вместо passwordhash может быть передан password. В поле from должно быть указано полное имя отправителя. Так как на сайте в профиле может быть не указано полное правильное имя пользователя, имеется возможность указать его отдельно. В поле postaddress необходимо указать свой полный почтовый адрес. На сайте не хранятся почтовые адреса пользователей. Адрес дефекта нужно указать чётко, чтоб было понятно в прокуратуре. Поле gibdd должно содержать название отделения ГИБДД, куда было направлено заявление. Для его получения можно воспользоваться запросом getgibddhead. Поле gibddre должно содержать содержательную часть ответа из ГИБДД и используется только в том случае, если этот ответ получен. Отправить заявление в прокуратуру можно, когда дефект находится в двух статусах: «просрочен» и «получен ответ из ГИБДД», в обоих случаях текст заявление будет разный, в первом случае — жалоба на бездействие ГИБДД, во втором — заявление о нарушении закнодательства о содержании и ремонте дорог и безопасности дорожного движения. В том случае, если дефект находится в другом статусе, будет выведена ошибка UNAPPROPRIATE_METHOD. Скрипты на сайте не проверяют валидность вводимых данных. Сгенерированный PDF-файл не хранится на сервере.

Комментариев нет:

Отправить комментарий

Ублюдочный Гугл поломал форму комментариев. Извините.