Эволюция Wialon API

tl;dr: обернуть существующее Remote API удобными/семантическими методами, реализовать интерактивную документацию методов (как у flespi, или как у ВКонтакте), обратную API-документацию (как реализуются те или иные фичи WH API-методами), примеры каких-то базовых юзкейсов/best practices использования API.

Здравствуйте.

Данный пост — результат просмотра последних 180 топиков в этой категории форума (точнее половина из этой, половина из английской), примерно полтора года опыта использования JavaScript SDK, немного использования чистого Remote API.

Судя по форуму, 40%+ топиков имеют довольно тривиальные проблемы, в основном вызванные отсутствием конкретных примеров каких-то базовых вещей (либо сложностями их найти), затем с error:4 (большая часть просто из-за того, что x-www-form-urlencoded параметры не экранированы, остальные из-за каких-то деталей документации метода, которые были проигнорированы/не поняты), ну и со сложностью выполнения/получения результатов отчётов.

Среди оставшихся 60%- — действительно сложные вопросы, которые проблематично решить самостоятельно и невозможно предугадать, свои решения, запросы на разработки, ну и просто темы не по теме.

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

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

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

Но мы, как разработчики, можем попробовать сделать что-то лучше прямо сейчас «на своей стороне».

Я предлагаю начать Open-source проект веб-приложения, предоставляющего обёртку над текущим Remote API.

Что это нам даст?

• Упрощение входных параметров методов, которые исторически так сложились вследствие добавления возможностей.
• Валидация корректности входных параметров для сообщения конкретных ошибок.
• Расшифровка полей результатов там, где экономия на этом незначительна (а там где это имеет смысл, обычно можно применить статическую типизацию и достигнуть большей экономии, чем сейчас).
• Предоставление реализации функционала, который часто реализуется из приложения в приложение, хотя мог бы быть реализован на серверной стороне и работать автоматически. Например, сообщения о нахождении объектов в геозонах и наоборот (в WH сейчас это довольно сложная система, работающая на клиенте, запрашивающая get_zones_by_point при изменении позиций, предварительно фильтруя по BBox'ам).
• Возможность фильтрации ненужных данных, которые в данный момент нельзя отфильтровать.
• Возможность группировать запросы в один. Например, создавать аккаунты одним запросом вместо трёх, создавать объекты/пользователей сразу со всеми нужными параметрами одним запросом.
• Возможность разбивать результаты одного запроса, а не получать 100мб+ (ок, скорее всего он будет сжат до ≈20мб) JSON'а, парсинг которого в случае веб-приложений в любом случае (ну ладно, существуют асинхронные JSON-парсеры) подвесит интерфейс минимум на секунду-другую, плюс его нужно ждать, хотя мы могли бы начать как-то использовать часть данных сразу.
• Возможность использования самых современных трафиков транспортов. Поллинг avl_evts вполне можно заменить вебсокетами, скорость получения данных от этого не изменится (обёртка всё равно будет использовать его), но трафик как минимум из приложения уменьшится за счёт пустых событий. Можно зачем-нибудь сделать MQTT-интерфейс.

Много чего можно ещё придумать и мало чего сделать на самом деле.

Как я себе это вижу на данный момент:

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

Очевидно, что покрыть все текущие возможности Wialon крайне трудозатратно и данная затея в данный момент ставит целью не заменить текущее API, а сделать процесс входа в wialon-разработку более безболезненным и быстрым, нежели он есть сейчас, чтобы начать что-то делать можно было уже спустя 5-10 минут чтения интро, а затем уже разбираться по ходу дела. Плюс сгенерировать примеров использования API, кода для решения общих задач, обкатать идеи, которые затем потенциально могут быть использованы в настоящем API. Ну и, если всё хорошо сделать, будет куда удобнее делать одноразовые скрипты, которые должны как-то изменить/выгрузить данные.

Буду рад выслушать ваши предложения/замечания/вопросы.

disclaimer: Данный пост никоим образом не выражает чего-либо от лица Gurtam, это исключительно мнение одного из разработчиков под Wialon API.