Поддерживать актуальность документации можно и вручную, но лучше проектировать «самодокументирующееся» API
Сейчас http стал фактически стандартом обмена между разными системами. Исключением является обмен файлами, на случай отсутствия связи.
Для кого-то давно, для кого-то недавно в 1С появились веб сервисы. Почти 20 лет назад они поражали сразу двумя особенностями. С одной стороны, довольно высокой сложностью, с другой стороны тем, что SOAP вполне описывает структуру данных. Некоторым разочарованием было только то, что 1С так и не добавила комментарии в описание WSDL. Если бы комментарии имелись, то, возможно, это была бы полноценная документация API.
Позже появились http сервисы, и 1Сники с восторгом начали их осваивать. Разработка сильно упростилась. Настолько, что хорошее документирование интерфейсов стало скорее исключением, чем правилом.
Оглядевшись, мы увидим, что в других системах с документацией тоже не очень хорошо. Например, OpenAPI строит документацию по коду и хранит её отдельно. Это означает, что актуальность не гарантирована.
Возникает справедливое желание совместить простоту работы http сервисов с «автодокументированием» wsdl. Задача не из трудных. Важно лишь задуматься об этом.
Сложность лишь в том, чтобы принять решение своевременно. Архитектуру API следует продумывать до того, как сделан первый метод. Переделывать на порядок труднее, а если API уже используется, то на два порядка.
При построении API логично на входе расположить функцию-стрелочника, который будет на уровне конфигурации определять, как именно следует обработать тот или иной запрос. Дальнейшая работа значительно упрощается.
Работа «стрелочника» проста и понятна. Понять, что требуется, и передать управление тому, кто может исполнить требуемое.
Кроме прикладной логики, например, записать или прочитать данные, клиент может задать нашему API вопрос «Что умеешь?». Ответ на этот вопрос и будет документацией.
Очень удобно, когда API умеет отвечать на запрос «что умеешь?». Причём как в человекочитаемом, так и в формате, пригодном для автоматической обработки.
При внедрении решений 1С документацию к API чаще всего пишет разработчик. Так пусть сразу и пишет её в коде! И не потребуется использовать костыли, в виде построения документации по комментариям. Достаточно одного параметра на входе, по которому станет понятно, что требуется вернуть описание API.
В объектно-ориентированных языках вопрос решается совсем просто. За каждый метод API назначаем класс-обработчик, внутри которого пишем метод, ответственный за документацию.
В 1С возможны другие решения. Например, можно в стиле «Конвертации данных 2» сделать справочник методов API, в котором описать параметры и добавить описание для программиста корреспондирующей системы. Отчёт по этому справочнику и будет документацией.
Ещё один вариант в том, чтобы написать в стиле «Конвертации данных 3» — с таблицами значений, ключами и портянками функций. Для каждого метода может быть три функции. Одна отвечает за запись, другая за чтение, третья возвращает описание.
Я выбрал стиль КД2.
Кто смутно мыслит, тот смутно излагает
«Если вы учёный, квантовый физик, и не можете в двух словах объяснить пятилетнему ребёнку, чем вы занимаетесь, — вы шарлатан», — Ричард Фейнман.
Разработчикам, как правило, мало интересны тонкости системы, с которой приходится налаживать обмен. Предубеждения одной системы могут оказаться несовместимыми с заблуждениями другой. Поэтому внутреннюю логику не стоит показывать наружу.
1С в типовых решениях всегда выносит внутренние термины и подходы в формат обмена. Ни разу не видел, чтобы какая-то сторонняя система использовала «универсальные» форматы 1С. Даже OData, один из самых простых API, вызывает головную боль у разработчиков других систем.
Часто создание API начинается с одного простого требования, например, «дайте нам остатки». Позже требования растут и ветвятся. На простой запрос хочется дать простой ответ, не заморачиваясь со строгой типизацией как в SOAP.
Управление легковым автомобилем не зависит от того, насколько всё сложно у него внутри.
Способность строить простые и понятные API является хорошей проверкой на понимание системы специалистом.
Да, существуют не только автомобили, но и самолёты и строго типизированные API, но их на порядок меньше, чем «велосипедов», работающих в каждом предприятии. Я не против SOAP как такового, а лишь за уместное его применение.
Что делать, если метод API работает слишком долго? Выход есть!
Не всегда получается сделать быстрый метод. Увеличивать таймаут http запросов тоже не всегда возможно. Есть целых три решения:
- «Асинх». Присвоим запросу идентификатор. Система, получившая запрос, сообщает, что начала обработку, «ждите ответа как соловей лета». Результат сохраняет, например, в регистре сведений. Получить результат можно через время запросом с таким же идентификатором.
- «Обратный вызов». После завершения работы метода API 1С может вызвать метод корреспондирующей системы. Увы, данный способ реализуем не всегда. У корреспондента может не быть входа.
- «Событийный подход» или webhook. Очень часто система сама знает, какие данные нужны корреспонденту. Нет смысла ждать. Можно отправлять данные по мере готовности на его API, если оно есть и доступно.
Если подумать головой, то три приведённых решения напрашиваются сами. Искусство состоит в том, чтобы все три подхода отрабатывал один код. Для всех методов API хорошо бы предусмотреть обработчики «после выборки данных», «после записи» или «перед отправкой». Это ещё один повод задуматься над архитектурой API до написания первой строки кода.
Каждому корреспонденту — своё API или всё-таки шина?
Плюсы шины очевидны. Это и гарантированная доставка сообщений, высокая доступность, и, главное, порядок во взаимодействии систем и даже экономия при обращении к платным сервисам. От каждой системы достаточно одного API, с которым взаимодействует шина.
Всем хороша шина, но это ещё одна система, которую нужно поддерживать, и, скорей всего, по ней нужен отдельный специалист, что накладно. Плюсы от шины данных проявляются в полный рост, когда требуется соединить много различных систем, и добавление в зоопарк ещё одного животного уже не играет большой роли.
Внедрение шины означает пересмотр взаимодействия всех систем. Большая и не очень понятная руководству затея. «Всё уже работает. Траты не обоснованы», — скажет начальник и будет прав.
Разработчик взгрустнёт и пойдёт писать интерфейс со всем зоопарком.
Нет смысла пытаться засунуть все системы в один большой API. Во-первых, через некоторое время станет невозможно понять, какой метод для какой системы создавался и на чём отразится его изменение. Во-вторых, неизбежно возникнут трудности с разделением прав.
Из вышеизложенного следует необходимость предусмотреть создание нескольких API. По одному на каждую систему, с которой строим обмен.
Как запутаться самому и запутать всех
Лучший способ устроить локальный хаос — сделать API, принимающий фрагменты кода и возвращающий результат исполнения кода.
Помимо очевидной дыры в безопасности исполнение стороннего кода это утеря контроля над системой. Разработчик перестаёт понимать, какие данные и как попадают в базу. Изменение системы, в том числе обновление типовой части могут привести к неработоспособности внешнего кода.
Решение исполнять сторонний код происходит либо от настойчивого продавливания размытых требований: «Дайте кнопу “Сделать всё”», либо от лени разработчика, который перекладывают свою работу на других.
API является уровнем абстракции над системой. Внутреннее устройство должно как можно меньше просвечивать через этот уровень абстракции. Платформа 1С хорошо изолирует разработчика от работы с SQL сервером, что позволило платформе работать с разными SQL серверами.
Второй способ запутаться это дать доступ в базу сторонним поставщикам
Данные из сторонних сервисов система должна забирать самостоятельно. Сервис предоставляет API, система под контролем своих администраторов обращается и забирает данные. Никак иначе.
Гибкость хуже воровства
Варианты отчётов изначально не предназначены для построения интерфейсов с другими системами, но использовать их возможно, несмотря на опасности.
Неоднократно приходилось слышать просьбы «Хотим видеть на сайте вот этот отчёт, только с оформлением в стиле личного кабинета». Можно, конечно, сформировать в 1С табличный документ и вернуть его в виде html. И выглядит это удовлетворительно. В оформление сайта не попадает, но заказчик часто готов мириться.
Более красивое решение — конвертировать результат в json и уже на клиенте преобразовать его с требуемым оформлением.
Большинство отчётов возможно получить в виде дерева значения, которое относительно несложно преобразуется в json. Если приложить усилия, то на каждой группировке отчёта можно описать свои поля.
Решение простое, красивое, с одним огромным «НО!». Варианты отчёта слишком легко правятся. Пользователь, не знающий о том, что этот вариант отчёта используется в API, может изменить его, и система начнёт врать.
Оказывается, что самым неочевидным и легко портящимся является период. Даже опытные аналитики и разработчики, проверяя работу отчёта, могут установить произвольный период, который автоматически сохранится. Ошибка в API проявится далеко не сразу. Это хуже, чем сломанный вариант отчёта.
Если вариант отчёта работает как метод API, перед его формированием необходимо программно проверять или устанавливать его ключевые настройки.
Также возможно создать отдельный вариант отчёта, скрытый от пользователей, и отдавать его результат. Говорят, что в БСП есть галка, запрещающая менять вариант отчёта, но её работоспособность надо проверять.
Критикуя — предлагай! Предлагая — исполняй!
Всё вышеизложенное я отразил в конструкторе API ЛеМурр. Точнее сначала написал Ле Мурра и только потом эту статью, где обобщил соображения, из которых исходил при создании расширения имени учёного кота Мурра.
Вступайте в нашу телеграмм-группу Инфостарт
