Откройте миру разрабатываемые вами API

Современный мир как никогда ранее благоприятствует разработчикам. У вас есть доступ к тысячам статей, миллионам ответов на вопросы на StackOverflow и миллиардам твитов, связанным с тех-индустрией. Ещё и GitHub недавно приобрёл npm.

Эффективные подготовительные буткамп-программы для разработчиков набирают обороты. Такие сайты, как Cloud Guru и Udemy, переворачивают традиционные подходы к обучению с ног на голову. Коротко говоря, если вы хотите создавать ПО, то у вас есть доступ ко всему необходимому.

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

Я призываю вас по мере создания собственного ПО подумать об этом заранее. Спецификация OpenAPI 3.0 уже доступна, и я настоятельно рекомендую начать её использовать. 

Почему? Это хороший вопрос, и сейчас я на него отвечу.

Это стандарт индустрии

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

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

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

Открытые API как раз об этом. Они поддерживаются сообществом и уже претерпели ряд преобразований на пути к своему текущему состоянию. Спецификация Open API прошла большой путь, начиная с изначально открытого проекта под названием Swagger. Сегодня же её используют такие крупнейшие компании как Google, eBay, Atlassian и др.

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

Это золотой стандарт. Именно такой на сегодня должна быть область разработки.

Это ваша документация

Слышали когда-нибудь о Markdown? Конечно же слышали — он повсюду. Даже если это слово не кажется вам знакомым, вы его точно встречали. Это просто язык разметки, упрощающий форматирование текста с возможностью последующего преобразования в более сложные форматы. OAS 3.0 использует его везде. 

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

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

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

Возможность проверки

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

if(!event.someProperty || isNaN(event.someProperty)){ return 400; }

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

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

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

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

Добавление проверки запроса поможет повысить продуктивность и уменьшит сложность.

Если вы используете бессерверные службы AWS вроде Lambda и API Gateway, проверка из OAS 3.0 особенно полезна, т.к. она не позволяет запуск лямбда-кода, пока не будет выполнена проверка запроса, сокращая ваши денежные расходы на запуски лямбда.

Расширяемость

OAS 3.0 имеет богатые возможности изначально, но если вам потребуется что-либо особенное, то это легко решается. Нужна помощь в работе с уже используемыми службами? В OAS 3.0 для этого также наверняка найдётся документированное расширение.

Реализация расширения размещается в коде или в ином использующем спецификацию компоненте. Но вы можете с лёгкостью добавить новое расширение, снабдив его префиксом x-. Например, если мне нужно создать новое расширение для автоматического обновления коллекции документации Postman, я могу объявить его в спецификации так:

openapi: 3.0.0 info: title: My Example OAS3.0 Spec description: Provide a meaningful example for my readers version: 1.0.0x-update-postman-documentation-collection: collectionName: Example OAS3.0 API autoIncrementVersionNumber: true

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

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

Прямая связь с AWS службами

В AWS имеется полный пакет расширений, которые по умолчанию интегрируются с API Gateway. Это позволяет вам с лёгкостью привязывать спецификацию к реальной инфраструктуре и добавлять такие компоненты, как лямбда-авторизаторы, преобразователи запроса и ответа, а также прокси напрямую к службам вроде DynamoDB и S3. Полный список поддерживаемых расширений вы можете найти здесь.

Если вы используете CloudFormation, то часть сценария развёртывания считывает расширения AWS и соответствующим образом настраивает ваш API Gateway. Неважно идёт ли речь о проксировании различных служб, конфигурировании CORS или установке конкретных параметров интеграции, настройка потребует всего четыре или пять строк.

На деле ваша спецификация OAS 3.0 и сценарий CloudFormation находятся в разных файлах. Сценарий CloudFormation обращается к спецификации в процессе развёртки и устанавливает всё, что вы в ней определили. 

Расширение границ

Несмотря на вашу сообразительность, велики шансы, что вы не продумали все возможности использования вашего приложения. Знакома ли вам теорема о бесконечных обезьянах?

Обезьяна, бесконечно ударяя по клавишам печатной машинки случайным образом, с высочайшей долей вероятности напечатает любой выбранный текст, хоть даже произведение Уильяма Шекспира.

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

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

Поэтому не стоит препятствовать инновации, держа в секрете ваши конечные точки. 

Начните прямо сейчас

Сейчас самое время привнести в мир больше пользы. На фоне пандемии COVID-19 мы, как никогда ранее, имеем возможность отдавать и оказывать помощь нашим сообществам.

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

Содействуйте реализации перемен, предоставив средства для изменения ситуации. Откройте ваши API, помогите другим, ведь все мы одна команда. Удачи! Делайте своё дело в удовольствие!

---

Перевод статьи Allen Helton: You Should Open Up That API You’ve Been Working On