На днях услышал о REST API для ПО, с которым работаю почти ежедневно. Обычно я использую SDK, но тут решил воспользоваться предложением на основе архитектуры REST. Это позволило бы быстро проводить POC (англ. proof of concept) в Postman и мгновенно проверять свои идеи.
Я большой фанат REST и проектирования API. Вот уже многие годы выступаю за разработку на приоритетной основе API (так называемый подход API-first). Вполне естественно, что первым делом я отправился на поиски соответствующей спецификации. Сначала немного поискал на GitHub, но безуспешно. Затем с этим вопросом обратился к специалисту по сопровождению ПО и получил в ответ одну единственную инструкцию curl:
curl -d SOMEBLOB https://{{baseurl}}/data/set/KEYNAME?token\=TOKENHERE
Само собой, я был немного разочарован. Она вызывала больше вопросов, чем давала ответов. Как будут выглядеть данные в ответе? Какой была схема тела запроса? А что насчет типа содержимого? Можно ли задействовать параметр запроса token в качестве заголовка Authorization? Есть ли другие конечные точки, которые можно использовать взамен? В общем, путь к знаниям оказался тернистым, а совсем не RESTful.
Попробовал вызвать конечную точку, но возникла ошибка. При этом я не знал, как ее исправить. Инструкция curl не особо помогает, когда дело касается устранения неисправностей.
Всего этого недопонимания можно было бы избежать, имейся под рукой общедоступная спецификация API. Какое-то время вы можете обходиться без нее, пока работаете над созданием функциональностей, которые помогают определять соответствие продукта рынку, но впоследствии она все равно понадобится. Со временем база пользователей будет расти, и у людей появятся вопросы о том, как она работает и какие функциональности доступны через HTTP.
Далее рассмотрим, что именно входит в спецификацию API и почему она так важна для долгосрочного успеха.
Содержание спецификации API
Спецификация API, такая как Open API, перечисляет конечные точки, схемы, ответы, параметры, безопасность и базовые URL для API. Она не оставляет места догадкам в процессе изучения набора функциональностей. Спецификации точно указывают, что требуется каждой конечной точке, какие ответы и почему вы получаете.
Рассмотрим пример из игры Acorn Hunt, которую я создаю:
/points:
post:
summary: Add or remove points from the caller in their active game
operationId: updatePoints
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- count
properties:
count:
type: integer
minimum: -10
maximum: 10
responses:
200:
description: The points were successfully added to the player score
content:
application/json:
schema:
type: object
required:
- score
properties:
score:
type: integer
409:
$ref: '#/components/responses/Conflict'
500:
$ref: '#/components/responses/UnknownError'
Данное определение конечной точки сообщает пользователям все, что им нужно знать для ее успешного вызова. В верхней части указаны path и метод http. Имеется краткая содержательная информация (summary) с точным описанием предоставляемой бизнес-функциональности. Как видим, схема тела запроса принимает только поле count в диапазоне от -10 до 10. Кроме того, предлагается список всех возможных ответов. В примере при успешном результате ожидается код состояния 200 со свойством score или 409/500 в случае ошибки.
При уменьшении уровня спецификация покажет все пути, поддерживаемые API. Пользователям, читающим спецификацию, не придется гадать, предоставляется ли конечная точка для выполнения конкретной задачи, поскольку все это в ней указано. Вы увидите не только пути, но и список серверов для каждой среды.
Пользователи могут привязать URL сервера к нужному пути, и готово! Приложение обеспечивается понятным и кратким описанием всех доступных конечных точек.
Примечание. На представленном выше изображении URL серверов вымышленные, так что использовать их не представляется возможным.
Преимущества спецификации API
Вернемся к ситуации, когда мне потребовалась информация об API, и пришлось обратиться к специалисту по сопровождению. Хорошо, если это разовая акция. Но что если обращаться с вопросами приходится по 20 раз на день? Или 50? И даже 1000?
Информация, известная только определенной группе людей, не выходит за рамки этого круга. А хуже всего то, что внешние пользователи узнают об API с чьих-то слов и рассказывают о нем знакомым. Затем эти знакомые передают информацию друзьям, а те своим друзьям и т.д. Вы когда-нибудь играли в “глухой телефон”? Как правило, в этой игре конечное сообщение очень сильно отличается от первоначального варианта. Представьте, что то же самое случилось с вашим API.
Отсутствие адекватной валидации на уровне запроса допускает ситуацию, когда пользователи могут отправлять в запросы совсем другие данные, чем ожидалось. Это может привести к нарушению целостности данных и возможному увеличению затрат на их хранение, что абсолютно никому не нужно.
При наличии спецификации API у вас всегда есть фиксированный ресурс, постоянно доступный для ознакомления. При этом не имеет значения, сколько разработчиков ее просматривают: один или миллион. Статическое определение на веб-странице обычно справляется с таким объемом. Пропадает необходимость привлекать разработчиков к обучению пользователей работе с API.
Помимо перечисленных внутренних преимуществ существуют и внешние.
Не все разработчики хотят обращаться к кому-то за разъяснениями. Многие просто откажутся от нового ПО, если его изучение сопряжено с чрезмерными сложностями. Спецификации снижают входной барьер в новую область знаний, предоставляя всю необходимую информацию.
Думаете, что спецификация API слишком низкоуровневый продукт, чтобы предлагать пользователям? Существует множество инструментов, которые отображают ее в виде понятных веб-страниц прямо из конвейера CI.
Вы не только обзаводитесь документацией, но, в зависимости от стека технологий, получаете возможность развернуть реализацию бэкенда прямо из нее!
При работе с AWS можно добавлять специальные расширения для создания валидации схемы и автоматического подключения напрямую к нисходящим сервисам. У нас с коллегами обсуждается вопрос об автоматизации всех процессов, начиная от генерации SDK, интеграции тестирования и заканчивая получением пользовательской документации непосредственно из спецификации.
Заключение
Спецификация API — ваш источник истины. Она определяет механизм разработки продукта. API является входной дверью приложения, предоставляя пользователям возможность использовать и расширять продукт в соответствии с их потребностями. Если вы оставляете своих пользователей с неотвеченными вопросами и недокументированными конечными точками, как они добьются успешных результатов? SDK зарекомендовали себя как отличные инструменты разработки, которые решают множество задач. Тем не менее они не охватывают всех проблем.
Веб-API, будь то REST или GraphQL, выступает в качестве вспомогательного средства. Он снижает входной барьер для новых пользователей, не требуя от них написания кода. Они просто открывают такой инструмент, как Postman или Insomnia, вводят ключ API и начинают тестировать.
Единый источник истины объединяет группу, ответственную за продукт, с командой разработки. Никаких “черных ящиков” или программирования вслепую. Контракт определен и реализован, и пользователи сразу открывают для себя новую функциональность. При определении соответствия продукта рынку ключевыми факторами успеха являются быстрая обратная связь и доработка. Спецификация API с подробным описанием доступных функциональностей — это самый быстрый способ рассказать о них пользователям и мотивировать на их использование.
Не нужно бросаться в крайности и сразу же применять подход API-first. Но если вы начнете рассматривать API как продукт, а спецификацию как его описание, то практически сразу ощутите все преимущества. Сделайте это своей приоритетной задачей, и вы увидите, как улучшается качество и растет заинтересованность пользователей.
Читайте также:
- 3 основных принципа несвязных приложений
- FastAPI, Flask или Streamlit: что выбрать для веб-разработки?
- Мои заметки по программной инженерии
Читайте нас в Telegram, VK и Дзен
Перевод статьи Allen Helton: Why API Specs Are the Backbone of Successful Development
