Всем привет! Делюсь очередным выпуском нашей рубрики «Открытый микрофон», тема этого выпуска — «Как написать свою первую спецификацию на REST API».

Спикером стала Мария Яковлева. Маша — ведущий аналитик Платформы Сфера, НОТА (Т1 Консалтинг). В интернете много описаний особенностей архитектурного стиля REST, но мало информации о том, как аналитику начать создавать качественные спецификации на REST-методы. Маша поделилась своим опытом и, что особенно ценно, ошибками, допущенными в работе. А ещё Маша систематизировала их, чтобы уберечь вас от них)

Ниже предлагаю расшифровку трансляции, ссылку на сам выпуск оставлю в конце статьи.

Алексей Сможенков, ведущий трансляции: Всем привет! Меня зовут Алексей Сможенков, и я буду ведущим нашего стрима.

Тема нашей сегодняшней трансляции звучит следующим образом: «Как написать свою первую спецификацию на REST API. Однако, несмотря на то, что звучит она достаточно хардово, я хочу внести некоторую интригу и сказать, что сам по себе доклад куда шире и глубже, чем просто описание технических деталей по работе с REST API. Приветствую нашего сегодняшнего эксперта — это Мария Яковлева, ведущий аналитик из команды Т1 Консалтинг.

Мария Яковлева, спикер: Всем привет, меня зовут Мария, на текущий момент являюсь ведущим аналитиком на платформе Сфера в холдинге Т1. Сегодня хочу рассказать вам о том, как написать свою первую спецификацию на REST API. Уже 7 лет я работаю в роли аналитика, начинала с внедрения SAP в нефтегазовом секторе, потом разрабатывала десктоп-ПО и веб-сервисы для нефтегазовой сферы, после чего перешла в разработку мобильных приложений для госсектора и с 2023 года примкнула к команде внедрения продуктов платформы Сфера. Хочу рассказать про план своего доклада – это будет кейс о том, как я впервые описывала метод REST API, где я разберу типичные ошибки на понятных примерах. И в конце доклада можно будет скачать чек-лист, что может входить в спецификацию на REST API, а также будет чек-лист, как написать первую спецификацию на REST API.

О чём доклад?

Чего не будет в докладе?

Сразу хочу предупредить, что в докладе я не буду перечислять методы REST API и их отличия, не буду перечислять сами принципы REST и сравнивать REST и RESTful, также не будет обзора инструментов для описания тестирования.

Почему я выбрала эту тему для доклада?

По данным канала «System Education», ситуация на рынке труда на территории России с ноября 2022 года по июль 2023 (она продолжается и сейчас), такова, что наблюдается двукратный рост вакансий аналитиков. Они проанализировали также самые востребованные навыки для аналитика, и мы видим, что в каждой второй вакансии требуются такие компетенции, как REST, проектирование, архитектура, BPMN, UML и API. Это все довольно востребованные компетенции, в 2024 году они также набирают обороты в запросах вакансий аналитиков.

Как аналитики могут взаимодействовать с REST API?

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

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

Как я пришла к этому?

Я работала в команде мобильной разработки, у нас была команда веб-сервиса, мы все занимались разработкой одного общего сервиса. У нас было REST API, общая база данных, мы получали одну и ту же информацию. Мы синхронно старались выпускать функциональность, у нас был общий бэк, и swagger описывали разработчики. Это важный комментарий, который позволит понять, почему потом у нас начались проблемы.

Спецификации на REST API велись аналитиками в Confluence. В команде веб-сервиса был архитектор, отдельный аналитик, кто проектировал методы, архитектор, который валидировал эти методы, а я описывала, как мы их будем встраивать в мобилку, с каких экранов методы будут вызываться. И вся эта связка хорошо работала до тех пор, пока не уменьшилось финансирование проекта, в команде произошли структурные изменения и изменились рамки проекта. Из команды веб-сервисов ушли архитектор и аналитик, который проектировал методы. И ко мне обратились с просьбой, чтобы я проектировала эти методы, так как я больше всего контактировала с теми, кто их описывал раньше.

Сначала казалось, что ничего сложного нет —  у нас же есть шаблон, описанные другими аналитиками методы, я уже знала теорию, читала книги по проектированию. Оказалось, что мы неверно заложили свою оценку на эту задачу. Мы не знали, что произошло разделение сущностей  — веб-сервис поддерживал сущности по-другому. Начались проблемы с тем, чтобы изменить наши макеты, на что дизайнеры сказали, что у них нет такого количества времени, чтобы всё это корректно сделать.

Когда я описывала спецификации, стало не хватать каких-то данных, мы не понимали, как мы раньше без них обходились, нам потребовались новые данные. Неправильно была реализована вся постановка, и мы её каким-то образом выпустили в прод, не проверив. И функциональность, опять же, работала так, как она должна была работать согласно спецификации. У нас начались проблемы в команде, мы начали ссориться, появились претензии друг к другу. Я решила уточнить у своих коллег в аналитических чатах, как у других компаний обстоят дела, неужели никто с такими проблемами не сталкивался. На что получила огромный фидбек о своих сложных кейсах и боли, с которой они столкнулись при проектировании REST API.  

Я подумала, что всю эту информацию надо систематизировать. В ходе систематизации я поняла, что это всё вписывается в концепцию обычного процесса выявления требований, описанного Карлом Вигерсом — выявление, анализ, спецификация, утверждение.

Далее я подробно расскажу, с чем мы столкнулись на каждом из этих этапов.

С какими ошибками мы столкнулись на стадии выявления требований?

1. Ознакомилась не со всеми необходимыми документами по API

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

2. Проблемы с планированием задачи

Когда команда веб-сервиса разделяла сущности, меня на этом планировании не было. Менеджеры этот момент не учли или не смогли договориться, и нас поставили перед фактом, что произошло разделение логики. А мы с точки зрения мобильного приложения не были к этому готовы, не были готовы ни постановки, ни задачи, ни макеты на это разделение логики.  

3. Ошибки при работе со стейкхолдерами

Расхожее мнение, что стейкхолдеры — это заказчики, внешние люди. Но при проектировании методов REST API, получается, что те же самые дизайнеры, тестировщики, разработчики, вся твоя команда, даже менеджер соседней команды — это тоже стейкхолдеры, чьи требования не просто нужно учитывать, а желательно фиксировать и делать краткое резюме по проведённой встрече.

4. Не рассылала краткое резюме по проведённой встрече

Я вряд ли здесь открою Америку, говоря, что надо фиксировать свои договорённости. Мне казалось, что, раз у нас дружная команда, проводим дейлики, то все договорённости мы учтём одинаково. А по факту каждый понял по-своему.

5. Внутри команды не было единого понимания по выполнению задачи

Поскольку у нас произошли изменения на проекте и задача переходила от одной команды к другой, не было точного понимания, когда и в какой срок будет передана задача, а что мы будем делать, если оказывается, что в команде веб-сервиса почему-то нет тестировщика. Мы столкнулись с проблемой коммуникации, это частая история, с которым сталкиваются многие команды, особенно при изменении рамок проекта.

Надо дополнительно подсвечивать, что у нас меняются, допустим, рамки проекта, и нужно заново передоговориться, например, о том, как мы будем задачи передавать друг другу. На тот момент мы этого не сделали. Разработчик сделал так, как он понял метод, потом оказалось, что никто из тестировщиков этот метод не проверил, что тестировщики мобильной команды оказались на больничном, мне как аналитику тоже никто не сказал, что нужно провести аналитическую приёмку и потестировать этот метод. Метод ушёл в прод. Мы достаточно быстро поправили, но, к сожалению, потеряли время, увеличили затраты на эту задачу.

С какими ошибками мы столкнулись на стадии анализа?

1. Проектировала методы для мобилки с отдельной логикой, не такой, как была на вебе

Если у нас несколько клиентов, конечно, нужно стараться делать одинаковую логику для всех клиентов, одинаково распределять, выделять сущности и для мобилки, и для веба. Это прям очень важно.

2. Не адаптировала параметры для разных типов клиентов

Мы все знаем, что мобильные приложения небольшие, на ладошке помещаются, и мы не всегда можем отобразить там полные текстовые поля, адреса, ФИО или других текстовых данных. В таких случаях часто в методе реализуют так, что делают параметр для полного адреса и для более короткого, для того чтобы отображать на разных типах клиентов разную полноту. Но это зато позволяет, во-первых, заранее проектировать параметры, заранее думать об этих ситуациях и понимать, что результат будет лучше, если мы как аналитики сразу будем думать и эти параметры предусматривать.

3. Не уточнила необходимость пагинации и кэширования

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

4. Не задумывалась о нагрузке и отказоустойчивости

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

Когда мы это только стали проектировать, я подсветила, что видела отчёты по нагрузке и что нам нежелательно вообще на этот метод нагружать именно таким образом, и что лучше сделать отдельный метод, который будет возвращать эти данные. Разработчики спорили со мной, были несогласны, апеллировали к тому, что я не архитектор и не могу такие советы по нагрузке давать. При этом получилось, что у нас метод перестал выдерживать необходимую нагрузку, в час пик система стала падать, и мы всё равно в следующий квартал ушли с задачей разделения одного метода на два, чтобы обеспечить требования по нагрузке отказоустойчивости системы.

Спойлер: не всё так грустно! В итоге мы функциональность выпустили, она в проде, я сама этой функциональностью пользуюсь, то есть не всё так плохо, как я рассказываю, просто хочется максимально поделиться всеми своими ошибками и опытом.

С какими ошибками мы столкнулись на этапе спецификации?

1. Копировала методы из спецификации в другую без учета ограничений, не задумываясь

Часто встречающаяся проблема — это скопировать метод из одной спецификации в другую без учёта ограничений, не задумываясь. Копипастить нужно аккуратно. Это касается и аналитиков, и разработчиков, которые тоже могут код так скопипастить, не сильно задумываясь о том, насколько он подходит под спецификацию. Это общий тоже совет, но он действенный.

2.  Использовала шаблон описания спецификации, принятый на проекте, не анализируя, насколько он подходит

Когда я стала использовать наш шаблон описания спецификации, я поняла, что он не совсем подходит, по крайней мере под текущий этап проекта, при условии, что у нас произошли изменения в команде. Мне было непонятно, например, какая у нас должна быть авторизация, надо ли подменять cookie в Postman, когда я буду тестировать разработанный метод. И у нас в шаблоне не хватало всех данных, чтобы наиболее полно метод описать.

Сначала казалось, что шаблон небольшой, я всё заполнила и какие ко мне могут быть ещё вопросы, я аналитик. Но по факту это меня привело к тому, что, когда метод был разработан и всё-таки пришёл ко мне в аналитическую приёмку, у меня начались вопросы: как мне его правильно в Postman протестировать, как указать все настройки? И, конечно, лучше бы я полнее описывала методы авторизации и аутентификации и сразу описала спецификации на сам метод.

3. Неправильное использование HTTP-методов и кодов ответа

Во многих проектах встречается неверное использование HTTP-методов и кодов ответов. Про это можно долго рассказывать. Есть такие проекты, где только GET используют. Об этом, наверное, очень много статей написано, но сам факт таков, что аналитику надо продумывать и коды ответов, и ошибки такие, чтобы пользователь мог прочитать и понять, что от него требуется. Совсем плохой тон, когда в ошибках приходит какая-то англоязычная надпись, непонятная пользователю.

4. Не описывала авторизацию и аутентификацию

Я уже рассказывала, что у нас не были описаны авторизация и аутентификация пользователя. Конечно, лучше её указать сразу в спецификации, чтобы потом проще было протестировать, провести аналитическую приёмку.

5. Отсутствие примеров запросов и ответов, их некорректное форматирование

Не на всех проектах, не во всех командах аналитики приводят примеры запросов и ответов, и обычно тестировщики очень огорчаются, если этого не делать. То есть для них это, конечно, тоже большое подспорье, если в спецификации сразу приведены эти примеры. А если они ещё красиво отформатированы и сразу понятно, какая структура запроса и ответа, то это намного упрощает в дальнейшем приёмку работы.

Какую информацию можно описать в спецификации на REST?

На слайде ниже я привела, какая информация обычно встречается — обведено фиолетовым цветом. То есть обычно описывают ресурс, с которым работает REST API, HTTP-запрос, структуру запросов и ответов, вписывают ошибки и коды и пример запросов / ответов. Мне кажется, что было бы не лишним ещё общую информацию об API описать, логику интеграции, пагинацию, авторизацию и аутентификацию и привести примеры интерфейсов, с которых будет происходить вызов API.

Ниже я приведу QR- код, по которому можно будет посмотреть эту информацию в виде чек-листа.

С какими ошибками мы столкнулись на стадии утверждения?

1. Не проверила, как спецификацию поняли разработчики

Когда я написала спецификацию, разработчик отсутствовал, мы встретились с его тимлидом, и тимлид сказал, что всё передаст, вопросов нет, спецификация хорошо описана. Но не тут-то было. Разработчик в итоге не всё понял,  где-то что-то скопипастил, в общем, реализовал не то, что было описано в спецификации.

2. Не привлекла к валидации спецификации архитектора / лида аналитиков

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

3. Не проводила приемочное тестирование реализованного REST

Я в его в итоге провела, но сделала это не с первого раза. Один раз разработчик просто не обратился ко мне, а тестировщиков не было, и это привело к проблемам. Я считаю, что аналитик должен проводить приёмочное тестирование, чтобы знать, что в твоей спецификации всё корректно реализовано. На второй итерации своей работы я тестировала в Postman разработанный метод, описывала, как я его тестировала, и тут переходим к следующей ошибке. 

4. Не оформила результат тестирования метода так, чтобы можно было воспроизвести другому человеку

Когда мы оформляем свои результаты, то другой аналитик или любой новый человек на проекте сможет воспользоваться ими, это экономит время и позволяет поддерживать эти требования более наглядными. У нас, например, была такая ситуация, когда я реализовывала другую функциональность, подробно расписала в задаче, как я тестировала, подменяла cookie в Postman, какими способами я протестировала, какие были параметры.

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

Как впервые написать спецификацию на метод REST API? Чек-листы

Мой опыт, про который я вам рассказала, я попыталась свести в чек-лист, он доступен по QR-коду ниже. Можно прямо в файле отмечать этапы, что сделано и что не сделано.

Если у вас заполнено более 80%, то у вас довольно подробная документация, скорее всего, вы не столкнётесь с описанными трудностями.

Если заполнено где-то 50-80%, то это повод для беспокойства, и можно попытаться по чек-листу понять, какие данные не описаны, почему они не описаны, возможно, не хватает каких-то компетенций или просто человек об этом ещё не задумывался. Стоит попытаться описать аспекты, которые ранее ускользали из внимания.

Если заполнено менее 50%, то нужно срочно риски подсвечивать команде, обращаться к ним за помощью, в общем, вместе с командой обсуждать и решать этот вопрос.

Вот два чек-листа: первый— о том, как впервые написать спецификацию на метод REST API, второй — какую информацию вообще можно описывать в спецификации на метод REST API.

Что почитать дополнительно?

Я много пользовалась двумя книгами: первая — «Проектирование веб-API» Арно Лоре. Кто-то ругает эту книгу, говорит, что она слишком сложная или устаревшая. На мой взгляд, это довольно хорошая книга, которая позволяет детально разобраться в проектировании веб-API. Вторая книга — «Микросервисы» Крейга Ричардсона, я сама ещё её читаю, в ней есть некоторые главы, которые как раз касаются проектирования REST API.

Что ещё посоветую?

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

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

Как реагировала команда на предлагаемые изменения?

Мы, конечно, не думали, что у нас начнутся такие сложности, что мы настолько сильно превысим оценку по этой задаче — а трудозатраты превысили оценку в два раза. Когда всё началось, конечно, у нас были напряжённые взаимоотношения, но команда у нас отличная, так что удалось преодолеть все эти сложности.

Поэтому я считаю что итог хороший, всё в проде. К изменениям мы в разное время относились по-разному. Был момент, когда мы были ими воодушевлены, был момент, когда мы очень страдали, что всё так плохо. А потом на ретроспективах мы стали об этом более прямо разговаривать и не просто обвинять друг друга, а пытаться совместно найти выход.

Как можно перейти от теории к практике?

Если такие задачи по проектированию API не встречаются в работе, то я бы попробовала найти какое-то открытое API и в Postman попробовать его потестировать и попытаться его описать, то есть начать хотя бы с описания имеющегося API. Также можно попросить коллег, которые уже описывали АPI, показать свои спецификации или свои шаблоны описания и из этих шаблонов тоже попытаться сделать вывод — что понятно, что непонятно, каких компетенций не хватает, чтобы в этом разобраться, уточнить, что-то почитать.

Самый лучший способ — это на практике пробовать, то есть либо учиться, либо открытые API тестировать.

Какие скиллы помогли преодолеть трудности, а какие удалось прокачать в процессе?

Прокачала надсистемное мышление, возможность абстрагироваться от текущих проблем и попытаться сделать выводы даже в не очень простых эмоциональных ситуациях. А что помогло — любовь к тому, чем я занимаюсь. Мне нравится заниматься своими задачами, было желание разобраться и выпустить эту функциональность. И, конечно, хорошая команда. Да, не всегда было просто договориться, но тем не менее — здорово, когда команда профессиональная, и ты понимаешь, что можешь положиться на этих людей.

Ниже оставляю запись самой трансляции:

Всем спасибо и до встреч!