Узнайте, почему спецификации API необходимы для долгосрочного успеха каждого приложения и что вы теряете, если у вас их нет

На днях кто-то рассказал мне о REST API для некоторых программ, которыми я пользуюсь почти ежедневно. Обычно я использую их SDK, но ухватился за возможность использовать предложение на основе REST. Я мог быстро вычислить POC в Postman и проверить свои идеи за считанные секунды.

Я большой поклонник дизайна REST и API. Я был сторонником API-first development в течение многих лет. Поэтому, естественно, первое, что я делаю, это пытаюсь найти спецификацию. Я немного покопался в 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. Это устраняет все догадки при изучении набора функций. Спецификации точно сообщают вам, что нужно каждой конечной точке, какие ответы вы можете получить и почему вы их получите.

Возьмем пример из игры, которую я создаю, Охота за желудями.

/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. В нем есть содержательное резюме, которое точно сообщает читателям, какие бизнес-функции он предоставляет. Мы видим, что схема тела запроса принимает только поле count в диапазоне от -10 до 10. Наконец, мы видим список всех возможных ответов. Мы ожидаем код состояния 200 со свойством score в случае успеха или 409 или 500 в случае ошибки.

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

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

Примечание. URL-адреса серверов на изображении выше выдуманы и не будут разрешены, если вы попробуете их самостоятельно.

Преимущества наличия спецификаций API

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

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

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

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

Помимо внутренних преимуществ, заключающихся в том, что ваши разработчики не будут обучать других вашему API, у вас есть и внешние преимущества.

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

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

Вы не только получаете документацию, но, в зависимости от вашего технического стека, вы также можете развернуть внутреннюю реализацию прямо из нее!

Если вы используете AWS, есть расширения, которые вы можете добавить для проверки схемы сборки и автоматического подключения напрямую к нижестоящим сервисам. Я говорю с Андресом Морено об автоматизации всего, от генерации SDK до интеграционного тестирования и потребительской документации прямо из спецификации в подкасте Ready, Set, Cloud.

Последние мысли

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

Веб-API, будь то REST или GraphQL, является средством реализации. Это снижает входной барьер для новых пользователей, не требуя от них написания кода. Им просто нужно открыть такой инструмент, как Почтальон или Бессонница, подключить свой ключ API и протестировать.

Единый источник достоверной информации объединяет вашу команду продукта с командой разработчиков. Здесь нет никакого «кодирования в темноте» или «черных ящиков». Контракт определен и реализован; тогда ваши потребители смогут сразу открыть для себя новые функции. При установлении соответствия продукта рынку быстрая обратная связь и повторение являются ключом к успеху. Спецификация API с подробным описанием доступных функций — это самый быстрый способ сделать ваши функции известными и заставить пользователей опробовать их.

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

Удачного кодирования!