Обновление документации API

Что такое API

Application Programming Interface, интерфейс программирования приложения. Это не графический интерфейс, а программный — через него приложение принимает команды от других программ. 

Для услуг DDoS-Guard тоже есть API. С его помощью можно автоматизировать действия в личном кабинете — например, написать программу, которая меняет настройки защиты в зависимости от нагрузки на сервер.

Как было раньше

Раньше документация представляла собой текстовые файлы RST, в которых функции API описывались в свободной форме. За годы в текстах накопились уточнения, замечания и примеры от разработчиков — часто их было больше, чем главной информации о методе. Запутанная документация отпугивала новых пользователей сложностью и устаревшим форматом.
При этом были и особенности, которые хотелось сохранить в новой версии — веб-интерфейс с разделением API по услугам и модулям, поддержка описаний на двух языках.

Что изменилось

Главное — мы переписали документацию в формате OpenAPI. Этот популярный стандарт давно используется для описания внутренних API и заслужил любовь разработчиков DDoS-Guard — поэтому именно он стал основой публичного API. В процессе отредактировали и сократили описания, исправили фактические ошибки, а также добавили два новых раздела: управление лимитом запросов и правилами защиты.

Из прошлой версии сохранили разделение по модулям и услугам — так пользователям проще понимать, какое API относится к их услуге. Для веб-интерфейса разработали собственное решение, своего рода каталог, в котором можно удобно переключаться между файлами OpenAPI. Для просмотра файла используется классический интерфейс Swagger UI.

Не забыли и про поддержку двух языков — тексты пишем сразу на русском и английском, после чего из них автоматически генерируются два параллельных файла YAML.

Написанием новой документации занимались не только разработчики и тестировщики, но и UX-писатели. Это помогло сделать тексты лаконичнее и понятнее, унифицировать определения с интерфейсом и инструкциями. Еще добавили ссылки на пользовательские инструкции в Базе знаний, чтобы было проще сопоставить методы API с функциями личного кабинета. 

Возможности для пользователей

Документация по стандарту OpenAPI позволит разработчикам со стороны клиента быстрее разобраться в API DDoS-Guard — в этом помогут привычный формат с примерами запросов и ответов, подробные описания, ссылки на пользовательские инструкции и лог изменений. Автоматизировать работы стало проще —  например, из спецификации можно сгенерировать клиент актуальной версии
Каталог API будет играть большую роль в дальнейшем развитии документации. У нас получилось создать гибкое решение, которое дает удобный интерфейс для работы с десятками файлов OpenAPI на нескольких языках.