1

Эволюция Wialon API

Тема: Эволюция 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.

2

Эволюция Wialon API

Re: Эволюция Wialon API

rual молодец)

Пара вопросов
- Речь идёт о прослойке на python/nodejs/go? Если так, то будучи open-source, она будет размещаться на серверах клиентов. При изменении логики Remote API вся эта система может легко урониться..
- Т.к весь этот проект - только обёртка, принципиально нового функционала она не даст. Просто завернёт в красивую обёртку тот Remote API, который и так работает и решает свои задачи. Легче станет только новичкам, впервые увидевшим Remote API. Так может сконцентрироваться на них, без лишних инноваций? Больше примеров, статей, скриптов, репа со шаблонами на github? имхо, для новичков эта информация полезнее, чем новая обёртка, которая не обкатана в бою и которую всё равно надо изучать...

your shmi

3

Эволюция Wialon API

(29/06/2018 10:44:22 отредактировано SAT)

Re: Эволюция Wialon API

shmi пишет:

...Т.к весь этот проект - только обёртка, принципиально нового функционала она не даст. Просто завернёт в красивую обёртку тот Remote API, который и так работает и решает свои задачи. Легче станет только новичкам, впервые увидевшим Remote API.

В программировании, в общем-то, всё - обертка над ассемблером. А вон некоторые в своё время  C++ с ООП наворотили для удобства и минимизации ошибок разработки.  Не ограничились примерами исторически сложившихся вызовов DOS-прерываний ))

PS Возможно, если часть предложений rual  переформулировать  (завернуть в красивую обертку) через понятия инкапсуляции данных, базовых методов  и т. п. - предложение будет выглядеть заманчивей ?

"Если вы не можете объяснить это своей бабушке, вы сами этого не понимаете."  А.Эйнштейн
4

Эволюция Wialon API

Re: Эволюция Wialon API

shmi пишет:

При изменении логики Remote API вся эта система может легко урониться.

Я уж надеюсь, что API всегда будет оставаться обратно совместимым и логика меняться не должна. Если же она внезапно меняется — наличие прослойки только плюс, ибо можно гарантировать совместимость как минимум её, переписывая только её, а не весь код, использующий старые методы.

shmi пишет:

Т.к весь этот проект - только обёртка, принципиально нового функционала она не даст. Просто завернёт в красивую обёртку тот Remote API, который и так работает и решает свои задачи. Легче станет только новичкам, впервые увидевшим Remote API. Так может сконцентрироваться на них, без лишних инноваций? Больше примеров, статей, скриптов, репа со шаблонами на github? имхо, для новичков эта информация полезнее, чем новая обёртка, которая не обкатана в бою и которую всё равно надо изучать.

Всё так. Но примеры/статьи/скрипты/прочее для текущего API — это дело Gurtam, лично мне как разработчику это всё не нужно, ибо я достаточно хорошо разбираюсь в текущем API, зачем мне затрачивать свои личные ресурсы на то, что я в итоге не буду использовать сам? Мой интерес в данной движухе — получить опыт создания сложных серверных систем с особыми требованиями (вроде перезагрузки сервера для обновления кода без потери активных сессий), ну и если мне захочется сделать какую-то интеграцию с Wialon — использовать его. Ещё иногда на форуме проскакивают какие-то реальные задачи людей, которые вроде бы должны решаться просто, хочешь за 10-15 минут накидать реализацию в Playground'е и оказывается, что это делать довольно муторно и времени нужно куда больше и приходится обходиться просто указанием ссылок на необходимые методы и схему работы.

Ну и как я уже сказал — побочным эффектом должно стать и создание материалов для текущего API, ибо во-первых в документации методов будет объясняться, какие реальные API-методы были использованы и можно будет посмотреть реальный код их использования.

5

Эволюция Wialon API

(29/06/2018 12:57:58 отредактировано bako)

Re: Эволюция Wialon API

API может быть тысячу раз крут и функционален, но какой в этом толк, если сторонний девелопер плачет после прочтения документации?
Зачем весь этот функционал стороннему API разработчику, когда в support пишет mid (mid developer, Карл!) , он смотрит в документацию и говорит "тут ничего непонятно", "куда отсылать запросы", "какие параметры обязательные, какие нет?" . Он бы и рад что-то написать, но от прочтения документации по API он только больше путается, по крайней мере в нашем отделе создается именно такое впечатление. В этом случае мы предоставляем практически полную последовательность запросов с флагами и параметрами.
Скилл разработчика важен, но сейчас многие платформы заботятся еще и о том, чтобы создать простые, удобные и понятные инструменты и интерфейсы для сторонних девелоперов. [Captain Obvious]Это один из главных факторов популяризации платформы[/Captain Obvious], и будет круто, если наш API или оболочка для него будет достаточно простой, удобной и понятной. Мне идея нравится.

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

Technical Support Specialist
Gurtam