RU:JOSM/Plugins/GeoChat/API

Интерфейс общения с сервером. Всё идёт через HTTP-запросы GET. Название действия передаётся в параметре action, также для большинства запросов нужны координаты lat и lon (в WGS-84). Возвращается либо список сообщений, либо сообщение об ошибке/успехе. Формат всех ответов -- json-хэш.

Сервер находится по адресу https://zverik.dev.openstreetmap.org/osmochat.php.

Регистрация

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

?action=register&lat=...&lon=...&name=...

Регистрирует пользователя с именем name, находящегося по указанным координатам. Вернёт ошибку, если имя уже занято. Имена очищаются после выхода из системы, либо спустя час после последнего запроса данных. При успешном завершении возвращает в поле uid идентификатор пользователя, который требуется для всех остальных функций.

?action=logout&uid=...

Освобождает идентификатор пользователя и его имя.

?action=whoami&uid=...

Возвращает имя зарегистрированного пользователя. Полезно, если идентификаторы сохраняются между сессиями.

Загрузка сообщений

?action=get&lat=...&lon=...&uid=...

Ищет все сообщения в некотором радиусе от указанной точки. Радиус задаётся сервером и в настоящее время равен 20 километрам. Возвращает JSON-хэш с тремя массивами: messages с публичными сообщениями, private с личными сообщениями и users со списком и координатами ближайших пользователей.

Сообщения отсортированны по времени (новые в конце), каждое сообщение — хэш со следующими значениями:

Ключ	Что хранит
id	Уникальный идентификатор сообщения. Нумерация для личных и общих сообщений сквозная. Рекомендуется использовать параметр &lastid=... для подгрузки новых сообщений; в нём указывается идентификатор последнего полученного сообщения.
lon, lat	Координаты сообщения.
time	Время отправки сообщения в формате DD-MM-YYYY HH:MM:SS. Обычно в зоне UTC, но можно "сверить часы", послав серверу запрос ?action=now
timestamp	Метка времени в формате UNIX.
author	Логин автора сообщения.
message	Само сообщение
incoming	false, если сообщение отправлено пользователем, делающим запрос.

Для личных сообщений добавлено поле recipient с именем пользователя, которому адресовано сообщение.

Каждый элемент массива users хранит три значения: имя в поле name и координаты в lat, lon.

Добавление сообщения

?action=post&lat=...&lon=...&uid=...&message=...

Отправляет на сервер сообщение по заданным координатам. Для личных сообщений нужно добавить параметр &to=... с именем адресата. Если адресат не зарегистрирован, сервер вернёт ошибку.

Сообщения автоматически удаляются из базы через несколько часов после отправки.