Проектирование и разработка API с помощью TypeSpec

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

За кулисами был разработан новый язык, который Microsoft назвала CADL, Concise API Design Language. Опираясь на концепции TypeScript и Bicep, CADL позволил определять и описывать API таким образом, чтобы было удобно использовать код для определения операций API, а затем компилировать результат в виде определения OpenAPI. Он также позволял определять ограждения и общие стандарты определения в виде библиотек, помогая архитекторам и разработчикам сотрудничать при проектировании API. CADL стал шагом вперед в проектировании API, позволяя создать 500-строчное определение OpenAPI всего за 50 строк кода.

Такие инструменты, как CADL, являются ключевыми для поддержки таких массивных платформ, как Azure, которые перекомпилируют свои API по несколько раз в день. Им нужны согласованные API, которые могут использовать пользователи и службы. Современные API - это ключевая зависимость для клиентских приложений, для инструментов разработчика и для многого другого. Обеспечение корректности определений публичных OpenAPI - это ключ к предоставлению необходимой поддержки, а также возможность использования хост-сервисом автоматизированных тестов и генерации документации.

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

От CADL к TypeSpec

За год или около того с тех пор, как я в последний раз писал о CADL, произошло много событий. Самое очевидное изменение - это новое название TypeSpec, которое указывает на его наследие в сильно типизированных языках и его роль в создании и поддержке спецификаций API. Microsoft описывает TypeSpec как нечто большее, чем язык, называя его "платформой", поскольку он объединяет язык и инструменты, необходимые для создания общих типов данных, шаблонов API и рекомендаций по API в компоненты многократного использования.

TypeSpec широко используется в Microsoft, распространившись из своего первоначального дома в команде Azure SDK в команду Microsoft Graph и другие. То, что две крупнейшие и наиболее важные команды Microsoft по разработке API используют TypeSpec, является хорошим знаком для остальных, так как это свидетельствует о доверии к инструментарию и гарантирует, что базовый проект с открытым исходным кодом имеет активное сообщество разработчиков.

Конечно, проект с открытым исходным кодом, размещенный на GitHub, очень активен. Недавно был выпущен TypeSpec 0.56, который получил более 2000 коммитов. Большая часть кода написана на TypeScript и скомпилирована в JavaScript, поэтому она работает на большинстве систем разработки.

TypeSpec является кроссплатформенным и будет работать везде, где работает Node.js. Установка осуществляется через npm. Хотя для написания кода TypeSpec можно использовать любой редактор, команда рекомендует использовать Visual Studio Code, так как расширение TypeSpec для VS Code предоставляет языковой сервер и поддержку общих переменных окружения. Оно ведет себя так же, как и большинство языковых расширений VS Code, предоставляя инструменты диагностики, подсветку синтаксиса и завершение кода IntelliSense. Более крупные проекты могут воспользоваться аналогичным расширением для Visual Studio.

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

На сайте TypeSpec есть полезная игровая площадка, позволяющая экспериментировать с различными определениями API. Вы можете быстро увидеть, как код примера компилируется с определением API: примеры включают REST, HTTP, буферы протокола и схему JSON. Наличие альтернативных определений может помочь при переходе от одного типа API к другому.

Приятно видеть поддержку буферов протокола в TypeSpec, поскольку они используются для определения вызовов gRPC, которые становятся все более важными для создания высокопроизводительных API микросервисов. Эта поддержка также должна помочь в кросс-облачной разработке, поскольку буферы протокола используются для многих сервисов Google Cloud Platform.

Начало работы с TypeSpec

Установка проста, и после загрузки TypeSpec CLI, tsp, вы можете приступить к созданию своего первого определения API. Инструмент использует интерактивный процесс для выбора шаблона API и соответствующего набора библиотек для определения API, на которое вы ориентируетесь, например openapi3 для текущего выпуска OpenAPI.

Следующим шагом будет установка зависимостей. Затем вы можете приступать к редактированию кода TypeSpec, работая в файле main.tsp. На сайте растущей документации есть много хорошей информации, хотя она ориентирована на работу с описаниями HTTP или OpenAPI. Тем не менее, это достаточно общие подходы к определению API, чтобы вы могли использовать их в качестве руководства для других форматов API и SDK.

Вы можете получить хорошее представление о работе с TypeSpec, создав базовый REST API и представив его в виде описания OpenAPI. Работа с кодом TypeSpec покажется вам очень знакомой, поскольку базовый синтаксис во многом напоминает такие языки, как C# и TypeScript. Для первого определения API начните с импорта библиотек для HTTP и REST, а затем определите свой сервис.

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

Пространства имен объединяют такие связанные элементы, как имена приложений, маршруты, используемые для доступа к определенным ресурсам, и базовую модель данных. Получив эти сведения, вы можете начать добавлять в маршруты HTTP-операции и любые специфические вызовы, которые необходимо выполнить. Другие варианты позволяют добавлять параметры в описание, что дает возможность определять более сложные структуры API. Такой подход означает, что вы можете использовать те же методы для GraphQL и других сервисов на основе HTTP; вы не ограничены REST API.

После того как вы написали описание API, пришло время предоставить его в выбранном формате. Для REST API вы можете использовать эмиттер OpenAPI версии 3, вызывая его при запуске компилятора TypeSpec. В качестве альтернативы можно добавить описание в конфигурационный файл текущего проекта, где оно будет автоматически вызываться при запуске компилятора. Эмиттеры являются ключевым элементом TypeSpec, поскольку они сопоставляют ваш код с описанием API. Microsoft предоставляет фреймворк для эмиттеров, который можно использовать для ускорения разработки собственных эмиттеров. Тем не менее, создание эмиттеров остается одной из самых сложных частей процесса.

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

Такие инструменты, как TypeSpec, становятся все более важной частью современного инструментария разработчика. Сервис-ориентированные архитектуры нуждаются в хорошо спроектированных и хорошо документированных API, которые должны быть определены до того, как мы начнем писать код по обе стороны от API. Поэтому приятно видеть, как инструмент, который изначально был разработан для облегчения жизни инженеров Microsoft, получает широкое распространение. Будет интересно посмотреть, как будет развиваться сообщество TypeSpec, и какие еще библиотеки и эмиттеры будут созданы сообществом.