Обзоры дизайна API мертвы. Да здравствуют обзоры дизайна API!

Jul 28, 2023

Домашняя страница InfoQ Статьи Обзоры дизайна API мертвы. Да здравствуют обзоры дизайна API!

22 мая 2023 г., чтение на 8 минут

к

Джейсон Хармон

рассмотрено

Томас Беттс

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

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

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

Защитите личности. Безопасные цифровые услуги. Обеспечьте масштабируемый и безопасный доступ пользователей к веб- и мобильным приложениям. Начать бесплатную пробную версию.

Что еще более важно, согласование дизайна API до того, как основная часть разработки будет завершена, может в значительной степени избежать обнаружений в последнюю минуту, которые ставят под угрозу сроки поставки (часто называемый подходом «сначала проектирование»). Использование формата спецификации, такого как OpenAPI (фактический стандарт для API HTTP/REST), дает возможность определить API до начала любой разработки, что позволяет гораздо раньше согласовывать и выявлять проблемы.

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

Вот некоторые ключевые предпосылки для обеспечения бесперебойного процесса:

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

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

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

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