О чем спич?
Цель данной статьи — описать основные сложности, с которыми пришлось столкнуться при работе с API, а также создать площадку для обсуждения того, в каких проектах использование данного API было успешным, какие сложности были преодолены.
В данный момент количество программистов, использующих данное API, по стране очень и очень невелико. Данный обзор, я полагаю, является первым в сети по заявленной теме.
Я не являюсь сотрудником Мегаплана. Статья не является пиаром и по своим тезисам больше похожа, скорее, на антипиар.
В любом случае мой опыт может оказаться полезным всем: как конечным пользователям, так и руководству компании.
Справедливости ради стоит сказать, что продукт развивается. Ждем от компании изменения ситуации с API данного продукта.
Общее впечатление
Выскажу свое сугубо личное ИМХО, мое личное впечатление. Прошу выслушать без обид:
1. API Мегаплана нуждается в полном перепроектировании, а не в исправлении. В том виде, в каком оно сейчас есть, API является не очень удобным, а местами и непригодным для построения серьезного софта.
2. Значительная часть проблем с API — это системные проблемы, решение которых лежит в плоскости управления проектом, а не в чисто технической плоскости.
Существующие проблемы
1. API по факту не предназначено для получения полных таблиц базы данных и их периодической синхронизации
Набор функций API с их обязательными входными параметрами, очевидно, проектировался по принципу: «у нас такая или похожая функция уже есть, давайте откроем этот код во внешний мир».
На форуме сотрудник Мегаплана признается: «Возможности api редко выходят за рамки возможностей функционала мегаплана.»
Этот подход является в корне неверным в том случае, когда пользователю нужны данные по всем сотрудникам компании, по всем проектам а также нужна периодическая синхронизация с базой данных Мегаплана для получения всех последних изменений по всем таблицам.
Пользователь должен иметь простой способ одним запросом получить любую таблицу базы Мегаплана целиком, а потом ее периодически синхронизировать.
Вот лишь один из множества примеров, когда пользователь пытается выкачать всю таблицу проектов целиком:
http://www.megaplan.ru/forum/f12/topic163/
В ответ предлагается вариант создания специального пользователя с правами директора и являющегося координатором всех остальных директоров, создать фильтр для этого пользователя в интерфейсе Мегаплана и использовать Id данного фильтра при запросах к API получая данные в цикле порциями по 100 проектов.
Другой пример: если к задаче был добавлен или удален тег, то нет никакой возможности получить только измененные данные. Пользователь должен выкачивать сотни задач с полной информацией по каждой задаче лишь для того, чтобы узнать, был ли за это время добавлен какой-то тег или нет.
Резюмируя сказанное: софт, который генерирует отчеты или предоставляет возможность работать с объектами Мегаплана через альтернативный интерфейс, построен на данном API быть либо не может, либо может, но с большим скрипом.
2. API является урезанным
Количество API функций, по всей видимости, составлялось по принципу: откроем наружу те функции о которых чаще всего просят. Но при построении больших отчетов нужна вся или почти вся база: почему бы просто не открыть наружу доступ ко всем строкам таблицам базы через функции API?
Примеры:
«Можно ли создавать пользовательские фильтры через АПИ?»
«Нет, фильтры можно создавать только из интерфейса. А по API — вызывать.»
http://www.megaplan.ru/forum/f12/topic169/
«Возможно ли получить даты отпусков сотрудников через API ?»
«Такой возможности пока нет.»
http://www.megaplan.ru/forum/f12/topic209/
Еще пример. Диалог по почте: «Как через АПИ получить информацию о правах сотрудника? А именно: входит ли данный сотрудник в группы: „Админы“, „Директора“, „HR-менеджеры“, „Администраторы проектов“ и так далее. Спасибо.»
Ответ службы поддержки: «Такой возможности в API нет.»
3. Изменения в API обрушивают клиентский софт
API не поддерживает совместное существование старых и новых версий. При изменениях API, компания Мегаплан без предупреждений, фактически, просто обрушивает весь софт, который уже работает с этим API.
Привожу часть диалога со службой поддержки:
«Был запрос на основе FilterId. Возвращал 400 проектов. Потом внезапно стал возвращать 50 проектов. Вы что-то меняли в АПИ?»
«Да, были введены ограничения на количество выводимой информации за раз...»
4. Количество ошибок в документации превышает разумные пределы
В документации приходилось сталкиваться с лишними входными параметрами или с незадокументированными выходными параметрами.
Отсутствует информация, какие входные параметры являются обязательными.
Отсутствуют диапазоны входных параметров. Например, параметр Limit имеет диапазон 1...100.
На выходе функций API, некоторые свойства объекта возвращаются всегда, а некоторые — не всегда в соответствии с существующей в Мегаплане схемой данных. О каждом свойстве возвращаемого объекта должно быть прописано являются ли оно обязательным или нет.
Диапазоны выходных данных не указаны. Например, свойство такое-то — строка — имеет диапазон 0...256 символов.
Старался не сильно мочить этих ребят, если где допустил неточность или ошибку, прошу меня извинить и поправить.
Продукту желаю развития и процветания.