В процессе проектирования API в больших масштабах требуется целенаправленное усилие для создания согласованности. Основное различие между набором API и тем, что ощущается как настоящая платформа, заключается в согласованности. В данном случае согласованность означает, что если вы используете несколько API, такие факторы, как соглашения об именовании, шаблоны взаимодействия, такие как постраничная навигация, и механизмы аутентификации, являются стандартными для всех.
Традиционно комитеты по проверке травмировали разработчиков API, обнаруживая проблемы, вызывающие задержки, когда разработка считалась завершенной. Хуже того, проектирование комитетом может взять верх, задерживая прогресс или поощряя разработчиков искать способы обойти процесс, чтобы избежать боли.
Чтобы по-настоящему раскрыть потенциал современной платформы, включение децентрализованного управления является гораздо более масштабируемым и вовлекающим подходом. Это просто означает, что каждая область или функциональная зона имеет эксперта по предметной области, который был обучен стандартам и общей архитектуре, чтобы быть хорошо подготовленным гидом для разработчиков API.
Что еще более важно, согласование дизайна API до завершения основной части разработки может в значительной степени избежать последних открытий, которые ставят под угрозу сроки поставки (часто называемые подходом "дизайн-первым"). Использование формата спецификации, такого как OpenAPI (де-факто стандарт для HTTP/"REST" API), предоставляет возможность определить API до начала разработки, что позволяет гораздо раньше достичь согласованности и выявить проблемы.
С учетом этого контекста давайте подробнее рассмотрим, как проводить обзоры дизайна API, и как разрабатывать процессы и готовить организацию, чтобы избежать затянутых сроков и отсутствия вовлеченности разработчиков.
Использование API — это очень концентрированный опыт, и поэтому влияние языка непропорционально выше, чем в большинстве других областей дизайна. У каждого члена команды может быть немного разный способ определения и описания различных терминов, что проявляется в путанице и снижении производительности для команд API.
Хотя порталы/документация API необходимы для отличного опыта разработчика, хорошо спроектированные API должны рассказывать большую часть истории без необходимости много думать об этом. Если термины знакомы потребителю, а шаблоны взаимодействия очевидны, то опыт может быть быстрым и безболезненным. Согласованность — это основное различие в опыте между набором API и тем, что ощущается как одна платформа.
При создании вашей программы API и процесса управления начните с общего языка. Хотя это может показаться невозможным на первый взгляд, определение ориентированного на клиента общего словаря/грамматики для вашей платформы является необходимым и общим ускорителем для организации. Многие термины могут иметь различные значения внутри компании, и что еще хуже, это часто термины, которые конечные потребители даже не узнают.
Выполнение этой работы заранее позволяет избежать конфликтов по поводу именования в процессе проектирования API. Проработайте каждую область с соответствующими заинтересованными сторонами, чтобы определить общую терминологию, и обеспечьте широкую доступность и осведомленность для дизайнеров API. И как только вы определились с внутренней стандартизацией терминов, не забудьте проверить, соответствует ли это вашим внешним потребностям. Использование языка клиентов и ориентированный на клиента взгляд на разработку API помогает командам избежать путаницы у клиентов с незнакомыми техническими терминами, поэтому убедитесь, что существует синхронизация между вашим внутренним пониманием и внешним пониманием.
Когда потребители API сталкиваются с моделями или параметрами, которые различаются между API, это может быть запутанным, разочаровывающим и трудоемким процессом. Например, если вы используете один API, который ссылается на контактную информацию, а следующий API на той же платформе использует совершенно другую модель, потребителям часто приходится устранять эти различия. Хуже того, могут возникнуть системные различия в обработке этих данных, создавая функциональные различия.
Как можно раньше определите общие компоненты (модели, параметры, заголовки и т.д.) и системы, которые их поддерживают. Ссылки на общие компоненты в определениях API обеспечивают более легкое внедрение будущих изменений этих компонентов на платформе, а также снижают излишнюю когнитивную нагрузку на потребителей API.
Чем больше общих компонентов у вас есть, тем больше возможностей для повышения согласованности, повторного использования, дальнейшего сотрудничества и повышения эффективности. Все мы в мире разработчиков любим метод "DRY" (Don’t Repeat Yourself — "Не повторяйся"), и чем больше общих компонентов, тем легче внедрять инновации, не создавая одно и то же с нуля снова и снова. Общие компоненты также позволяют вашей команде быстро масштабироваться, обучая новых разработчиков или заинтересованных лиц за пределами команды API с легкостью.
Для подавляющего большинства простых соглашений об именовании, шаблонов взаимодействия и механизмов аутентификации автоматизация с руководствами по стилю может быть предоставлена для выявления несогласованностей как можно раньше.
Первые руководства по стилю были разработаны между 2013-2015 годами, устанавливая ожидания по внешнему виду и ощущениям (также известным как DX) для команд разработчиков API. Необходимость согласованности дизайна была очевидна с самого начала разработки платформ API, и ранние усилия Paypal (я был частью этой команды в то время!) и Heroku привели к тому, что некоторые из первых руководств по стилю успешных программ были опубликованы публично.
Хотя существует множество инструментов автоматизации, которые могут помочь с руководствами по стилю, инструмент с открытым исходным кодом Spectral стал стандартом для определения наборов правил линтинга API. Согласование заранее соглашений для путей, параметров и других элементов, а также определение автоматизированных правил линтинга позволит избежать задержек из-за конфликтов по поводу того, какие соглашения являются "правильными". Проведите обсуждение один раз и определите правила... постарайтесь больше не говорить об этом; просто устраните ошибки линтинга!
Для стандартов дизайна, которые не могут быть автоматизированы, они должны быть задокументированы и легко доступны для дизайнеров API. Обучение, объясняющее важность автоматизированных и вручную проверенных правил, может мотивировать разработчиков полностью поддерживать инициативу и избегать сюрпризов и трений.
Хотя команда поддержки API должна существовать для курирования этих стандартов дизайна и развития сообщества, полномочия должны быть предоставлены в каждой функциональной области или домене.
Хотя стандарты API важны, знание системных ограничений, конкретных потребностей клиентов и сильных и слабых сторон организации лучше всего обрабатывается экспертом, который является частью этого мира. Если от централизованных членов команды поддержки API ожидается знание всего в компании, узкие места, ведущие к задержкам в поставке и отстранению разработчиков, практически гарантированы.
Обучающие семинары могут быть мощным инструментом для распространения осведомленности о важности стандартов API. Кроме того, вы часто обнаружите правильных экспертов по предметной области, которые могут предоставить полномочия для управления. Ищите людей, которые проявляют страсть к API (я часто называю их "группой повстанцев"), демонстрируют осознание важности согласованности и стандартов и имеют техническое уважение своих коллег и/или подчиненных.
Разработка успешного API будет включать множество людей по всей вашей организации, часто с контрастными навыками, некоторые из которых будут создавать и развертывать API, а другие будут на стратегической стороне бизнес-проблемы, определяя ценность вашего API. Не забудьте также о бизнес-заинтересованных сторонах, когда речь идет о том, кого вовлекать в обзор дизайна. Часто мы включаем только техническую сторону, и это может привести к неудаче позже. Чем больше перспектив, тем лучше!
Ваша платформа должна иметь менеджеров по продукту, которые согласны с общим составом портфеля/каталога API. Каталоги бывают разных форм, и они организуют ваши API, чтобы облегчить поиск того, что вам нужно, без необходимости точно знать, что вы ищете. Это позволяет потенциальным пользователям просматривать доступные API, сгруппированные по функциональности или другим интересам пользователей.
Хорошие каталоги доступны для поиска или фильтрации, чтобы разработчики могли легко сузить варианты, и они предлагают сопоставимые, легко усваиваемые детали для каждого API в каталоге, которые предлагают четкий путь вперед.
Для любого нового API, предложенного к разработке, функциональный обзор с вариантами использования и базовым именованием должен быть рассмотрен как можно раньше. Это обеспечивает согласованность языка, повторное использование и общее "соответствие" нового API с более широкой перспективой платформы.
Ваша команда поддержки должна иметь менеджеров по продукту, которые владеют процессом согласования портфеля, и каждый должен владеть управляемым набором доменов. Как минимум, регулярное место для обсуждения согласованности между PM, ответственными за конкретные домены, является ключевым.
Хотя это может показаться большим объемом работы, помните, что стандарты API должны развиваться через итерации. По мере разработки каждого API вы будете замечать возможности для уточнения стандартов. С учетом этого убедитесь, что основы охвачены в вашей предварительной работе, и убедитесь, что управляющие API четко понимают, как предлагать и принимать изменения в стандартах.
Если вы выполнили вышеуказанные предварительные условия, в обзоре дизайна API делать особо нечего! Если задействованы эксперты по предметной области, обзор дизайна часто может быть в значительной степени интегрирован в текущие усилия по проектированию. Если "соответствие" платформе согласовано заранее, рецензенты дизайна должны быть уверены, что этот API принадлежит общей картине. Кроме того, если дизайнеры API видят ошибки линтинга во время итераций, не должно быть обсуждений базовых соглашений, кроме обучения разработчиков важности различных правил линтинга или просто того, как устранить ошибки линтинга.
Не все можно автоматизировать, и иногда потребности продукта и архитектуры могут конфликтовать. Сделайте ваш обзор дизайна API временем, когда проверяются вручную применяемые соглашения, проверяется язык клиентов (так как это трудно автоматизировать), и окончательное согласование закрепляется. С учетом этого объема встречи часто можно пропустить, и асинхронные обсуждения часто могут быть достаточными.
Самое главное, внимательно следите за временем цикла обзора дизайна API... оно должно заметно сокращаться со временем, поскольку все больше децентрализованных экспертов по предметной области становятся более комфортными с существующими стандартами и тем, как принимать новые стандарты.
Улучшить тариф