Освобождение от одиночной работы: учимся совместной разработке API с Postman

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

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

Postman — мой основной инструмент для работы с API: отправка запросов, управление средами и запуск тестов. Я знаком со своим сольным рабочим процессом. Но я начал задаваться вопросом: что еще может предложить Postman в командной среде? Как это может улучшить сотрудничество и упростить процесс разработки?

Чтобы изучить эти вопросы, я начал работать над примером API, который я называю «X Nihilo».

Пример API: X Nihilo

X Nihilo помогает вам создавать твиты длиной 280 символов на основе параметров, которые вы сохраняете или отправляете. Вы указываете тему, цель, описание тона и описание аудитории. За кулисами API отправит запрос API OpenAI на завершение текста, что поможет сгенерировать твит.

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

Давайте рассмотрим мой основной рабочий процесс разработки API.

Работаю в одиночку: мой сольный рабочий процесс

Первым шагом в моем рабочем процессе является разработка API и написание спецификации OpenAPI. В Postman я создал новый API, а затем приступил к определению нового API.

После некоторых размышлений (и работы непосредственно с ChatGPT, который отлично подходил для создания исходной спецификации OpenAPI на основе моих описаний), я написал свою спецификацию:

Имея готовую спецификацию OpenAPI, я подошел к развилке дорог. Должен ли я настроить макет сервера и несколько примеров запросов и ответов, чтобы показать, как будет выглядеть взаимодействие с этим API? Или мне стоит начать писать код реализации?

Как индивидуальный разработчик, я могу быть только производителем API или потребителем API в любой момент времени. Поэтому я решил: не надо строить моки — потребителю во мне придется подождать. Давайте напишем код!

Спустя несколько мгновений…

Используя Node.js с Express и общаясь с базой данных PostgreSQL, я реализовал свой базовый API. Вот краткое изложение всего, что мне нужно было построить:

• POST /signin принимает username и password , проверяет подлинность записей в базе данных, а затем возвращает подписанный JWT, который можно использовать во всех последующих запросах.
• POST /generateTweet генерирует твит длиной не более 280 символов. Требуется topic (строка) и goal (строка). Он также принимает либо tone (строку), toneId (целочисленный идентификатор сохраненного тона), а также либо audience (строку), либо audienceId (целочисленный идентификатор сохраненной аудитории). Всякий раз, когда предоставляются строки tone и/или audience , API сохраняет их в базе данных.
• GET /tones возвращает список идентификаторов тонов и соответствующих строк. GET /audiences делает то же самое для повторно используемых строк аудитории.
• DELETE /tones принимает идентификатор тона и удаляет эту запись тона. DELETE /audiences делает то же самое для записей аудитории.

После завершения первоначальной реализации пришло время вернуться к Postman и начать выполнять некоторые запросы.

Создайте среду с переменными.

Сначала я создал новую среду под названием «Тест». Я добавил переменные для хранения моего root_url вместе с действительным username и password .

Создать коллекцию и запрос

Затем я создал новую коллекцию и добавил свой первый запрос: POST запрос к /signin , чтобы опробовать аутентификацию.

Когда мой сервер API работал в окне терминала, я отправил свой первый запрос.

Успех! Я получил свой токен, который мне понадобится при любых будущих запросах.

Я создал новый запрос, на этот раз для создания твита.

Я обязательно установил авторизацию на использование «токена на предъявителя» и предоставил токен, который только что получил по предыдущему запросу.

Вот ответ:

Оно работает!

Подведение итогов сольного подхода

Это краткий обзор моего сольного рабочего процесса. Конечно, по пути я бы сделал еще кое-что:

• Напишите сценарий предварительного запроса для выполнения запроса /signin , а затем установите переменную среды на основе токена в ответе.
• Создайте запросы для всех остальных конечных точек в спецификации OpenAPI.
• Напишите тесты для каждой конечной точки, стараясь покрыть крайние случаи.

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

Ага-момент: зачем рассматривать Postman для команд?

Что, если я больше не смогу быть сольным разработчиком API для X Nihilo? Это могло произойти по нескольким причинам:

• X Nihilo растет в размерах и сложности, и одного разработчика API уже недостаточно для его поддержки.
• X Nihilo — это лишь небольшая часть более крупного проекта API, в котором участвуют несколько разработчиков API или, возможно, даже несколько команд API.

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

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

Изучение возможностей команды Postman (корпоративной версии)

У Postman есть уровень бесплатного пользования, и он предлагает некоторые ограниченные функции совместной работы, которых может быть достаточно, если у вас небольшая команда (то есть не более трех разработчиков). Postman имеет дополнительные функции в рамках уровня Enterprise Essentials. Они отлично подходят для команд API в крупных организациях, которые повсеместно используют Postman.

Совместное использование рабочей области

Рабочая область позволяет вашим командам совместно работать над несколькими проектами API. Это замечательно, если разные команды работают над разными API, но эти API взаимодействуют друг с другом (что обычно имеет место в крупных организациях, занимающихся разработкой программного обеспечения).

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

Контроль версий

Хотя я заботился о контроле версий своего кода, будучи индивидуальным разработчиком API, меня не особо заботил контроль версий моих коллекций или сред Postman. Если я что-то изменю (изменю запрос, обновлю тест, удалю переменную среды), это повлияет только на меня. Ничего страшного.

Когда вы работаете в команде, вам определенно хочется знать, когда что-то меняется. А иногда нужно откатить изменения. К счастью, для команд, использующих Postman Enterprise, Postman предоставляет доступ к журналу изменений для коллекций, рабочих областей и API. Вы можете откатить коллекции к более ранним моментам времени. Вам, как разработчику API в команде, это понадобится. В большинстве случаев это потому, что Боб испортил коллекцию. Хотя иногда ты Боб.

Ролевой доступ и организация пользователей

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

В Postman вы можете назначать роли членам команды. Это влияет на тип доступа и уровень разрешений, которые имеет каждый член команды в команде или рабочей области.

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

Я также заметил, что Postman Enterprise поддерживает «захват домена». По сути, это означает, что вы можете настроить всех пользователей в вашей организации, предоставив доступ всем из (например) домена mycompany.biz .

Встроенные комментарии и обсуждения

У Postman есть одна функция совместной работы, которая доступна во всех его планах, а не только в Enterprise Essentials. Это возможность членов команды добавлять комментарии к коллекциям (к папкам, запросам, примерам или запросам на включение). Возможность комментировать и обсуждать непосредственно в Postman очень важна для командной разработки API. Поскольку большая часть работы вашей команды по разработке API будет выполняться в Postman, имеет смысл вести обсуждение именно там (а не в GitHub или каком-либо другом внешнем сервисе).

Командная разработка API: Почтальон на пути к победе

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

Повышенная эффективность

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

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

Меньше недоразумений

Когда все работают, используя один и тот же источник истины (ваше рабочее пространство), и они могут комментировать и общаться с помощью инструмента, который они используют для разработки, это приведет к меньшему количеству недопониманий. Ваша команда не будет терять время на путаницу по поводу того, должна ли эта конечная точка принимать параметры запроса или параметры пути. Все будет ясно.

Ключевой вывод

Я не знал, что Postman предназначен для команд и предприятий. Теперь, когда я знаю, вот мой главный вывод: командные игроки используют инструменты, которые полезны для команды.

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

Приятного кодирования!

Также опубликовано здесь .