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

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

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

Какие изменения API вызывают проблемы?

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

Изменение объекта ответа конечной точки

Предположим, у вас есть простой Flask API. Слева находится исходный API с единственной конечной точкой, которая возвращает такую ​​информацию, как идентификатор, имя, фамилия и полное имя. Вы решаете, что имя и фамилия являются избыточными, поскольку они могут быть получены из полного имени с помощью простой операции разделения; справа та же конечная точка с обновленным объектом ответа.

Если один из членов вашей команды использует ваш API, как показано во фрагменте кода ниже, изменение вашего API нарушит его код:

Такая ошибка также может возникнуть, если вы обновите имена или типы данных некоторых полей в вашем объекте ответа.

Изменение имени или структуры конечной точки

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

Если член команды использует API, как показано ниже, обновление нарушит его код, поскольку запрос будет сделан на несуществующий URL-адрес:

Обновление кода ответа конечной точки

Если вы обновите код ответа об ошибке для одной из ваших конечных точек API с 500 на 404, это может вызвать ошибку. Рассмотрим фрагмент кода ниже:

Если кто-то реализует обработку ошибок, но проверяет код состояния 500, новый код ответа 404 не будет обрабатываться. В результате код в блоке else будет выполнен и приведет к ошибке.

Обязательные необязательные параметры

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

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

Зачем делиться изменениями API со своей командой?

Помимо возможности критических изменений, есть и другие причины поделиться изменениями с вашей командой:

  • Члены команды могут предоставить ценную обратную связь, которая в противном случае может быть потеряна. Прежде чем предпринимать какие-либо действия, важно учитывать потенциальные последствия любого изменения API, и наличие вашей команды поможет вам сделать правильный выбор.
  • Им нужно подготовиться к изменениям API. Это может включать тестирование изменений или проверку совместимости их кода с новым API. Они должны иметь возможность учитывать изменения в своем коде; в противном случае они могут быть застигнуты врасплох неожиданными проблемами или ошибками, которые могут повредить отношениям между членами команды.
  • Изменения могут не только нарушить работу вашего API, но и нанести ущерб другим приложениям, использующим этот API. Если бы ваша команда не знала об изменениях, они не были бы готовы справиться с последствиями.

Как вы должны делиться изменениями API?

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

Обзоры кода

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

Такие инструменты, как Optic, позволяют просматривать эти типы изменений. Ниже приведен пример журнала изменений API, созданный Optic:

Optic также предлагает GitBot, который может добавлять журналы изменений API к каждому вашему запросу на вытягивание. Вот пример:

Каналы связи

Один из способов убедиться, что ваша команда знает о любых изменениях API, — использовать отдельный канал для обмена этими изменениями — например, канал Slack или список адресов электронной почты. Это гарантирует, что все будут знать, чего ожидать. Ниже приведены несколько советов по управлению таким каналом:

  • Сделайте канал доступным только для чтения, чтобы избежать каких-либо обсуждений. Ваша команда должна иметь возможность проверять уведомления, не просматривая другие сообщения.
  • Убедитесь, что потенциальные критические изменения четко отмечены. Вы можете добавить [IMPORTANT] в начало сообщения или добавить красный фон.
  • Сообщайте о таких изменениях заранее. Это даст вашей команде время подготовиться к ним.

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

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

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

Тестирование контракта API

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

Контракт должен быть принят всеми сторонами. Затем любые изменения, внесенные в API, перед утверждением должны пройти проверку контракта. Тестирование контрактов можно автоматизировать и включить в конвейер CI/CD. Инструменты тестирования контрактов включают Pact и Spring Cloud Contract.

Разработка на основе документации

Это похоже на разработку через тестирование, но вместо того, чтобы сначала писать тесты, вы пишете документацию до разработки своего API. Это означает, что любые изменения, внесенные в ваш API, должны быть сначала задокументированы. Вы можете следовать стандартам OpenAPI для написания документации или использовать сервис вроде Optic для компиляции документации вместо того, чтобы делать это вручную.

Версионные API

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

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

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

Вы также можете определить URL-адреса своего API, чтобы включить номер версии. Например:

www.myapi.com/v1/getBooks

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

Заключение

Даже небольшие изменения в объекте ответа или URL-адресе вашего API могут оказать большое влияние на других членов команды или заинтересованных лиц. Важно держать вашу команду в курсе. Наличие хорошего рабочего процесса для обмена изменениями API, их документирования и тестирования предотвратит ошибки или другие проблемы в будущем.

Один из способов улучшить рабочий процесс разработки API — использовать Optic для автоматизации тестирования, документирования и прозрачности изменений. Инструмент отслеживает и просматривает изменения API, создавая журнал изменений, а затем использует запросы, ответы и трафик к вашему API для создания документации.

Хотите знать больше? Optic — это проект с открытым исходным кодом, поэтому вы можете присоединиться к сообществу, усердно работая над тем, чтобы упростить написание документации.

Want to Connect?
This article was originally posted on realjavascriptproject.com
LinkedIn: https://www.linkedin.com/in/rahulbanerjee2699/