Как выбрать правильный стиль и технологию API

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

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

Нет лучшего стиля API

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

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

Ресурс.
Гипермедиа.
Запрос.
Туннель.
Основанный на событиях.

Затем мы выбираем подходящий стиль и технологию, которая хорошо работает для данного стиля.

Стиль ресурса

стиль ресурсов, как следует из названия, ориентирован на ресурсы. Многие современные API используют ресурсный стиль, и это легко проверить по популярности OpenAPI, который является наиболее популярным способом описания ресурсо-ориентированных API. В этом стиле основное внимание уделяется тому, какие ресурсы предоставлять потребителям, чтобы они могли взаимодействовать с этими ресурсами.

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

Для ресурсного стиля существует REST как архитектурный шаблон, но это не значит, что REST дает вам конкретные технологии. Для REST предпочтительнее выбрать HTTP в качестве протокола, а в отношении формата представления, вероятно, можно с уверенностью сказать, что JSON намного затмевает любое другое представление (например, XML, который был популярен до JSON). Когда клиентский запрос выполняется через RESTful API, он передает представление о состоянии ресурса в конечную точку.

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

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

Стиль гипермедиа

Как и в Интернете, наиболее важные пути между ресурсами можно перемещать, просто используя ссылки между ними (вместо того, чтобы знать каждый ресурс по отдельности и вводить его URI в адресной строке браузера); стиль гипермедиа делает то же самое, но для ресурсов API.

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

HATEOAS— это сокращение от Hypermedia As The Engine Of Application State. HATEOAS — это аспект REST, который позволяет осуществлять динамическую маршрутизацию ресурсов.

Есть два основных преимущества API гипермедиа по сравнению с API ресурсного стиля:

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

Все это звучит очень позитивно, потому что стиль Hypermedia предоставляет потребителям API необходимые знания, чтобы они сами могли узнать о вашем API и о том, какие ресурсы вы им предлагаете. Вы можете создать службу REST на основе гипермедиа с любым языком программирования и инфраструктурой, используемой в вашем стеке. Например, с помощью ASP.NET Web API или Spring Boot Rest API.

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

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

Стиль запроса

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

Одним из преимуществ стиля запроса является то, что каждый потребитель может запросить именно то, что он хочет. Это означает, что при правильно построенном запросе можно объединить результаты, которые потребовали бы многочисленных запросов в API-интерфейсах ресурсов/гипермедиа. Например, вместо того, чтобы отправлять несколько HTTP-запросов на разные конечные точки, вы можете POST сделать один «запрос» для всего, что вам нужно.

Что касается стиля запроса, вероятно, будет справедливо сказать, что GraphQL на сегодняшний день является самым популярным выбором, когда речь идет о создании одностраничных приложений (SPA). Это язык для запросов к базам данных из клиентских приложений. Большим преимуществом GraphQL является то, что он подключается к экосистеме на основе JSON. Хотя GraphQL не использует JSON для запросов, он возвращает результаты в формате JSON, что упрощает обработку в средах, ориентированных на JSON.

Хотя стиль запроса имеет незначительные недостатки по сравнению с преимуществами, мы можем выделить один из них — сложность запроса. Потребители API должны иметь хорошее представление о базовых данных и моделях запросов (чтобы они знали, как правильно использовать API запросов и делать эффективные запросы, чтобы избежать рекурсии или получения слишком большого количества вложенных ресурсов). Кроме того, реализовать упрощенный кеш с GraphQL сложнее, чем реализовать его в стиле ресурсов, потому что REST API имеют несколько конечных точек, они могут использовать собственное HTTP-кэширование, чтобы избежать повторной выборки ресурсов. Еще одна проблема с GraphQL — ограничение скорости, когда вы говорите, что мы разрешаем только это количество запросов.

Тем не менее, последние два упомянутых недостатка (кэширование и ограничение скорости) можно развить, внедрив шлюз API между клиентом и хранилищем данных, чтобы выиграть в этой ситуации. Например, шлюз API с открытым исходным кодом Apache APISIX обладает соответствующей способностью распознавать синтаксис GraphQL. Эффективно сопоставляя операторы GraphQL, передаваемые в запросах, он может отфильтровывать аномальный трафик для дальнейшего применения политик ограничения скорости и повышения производительности системы с помощью возможностей кэширования.

Туннельный стиль

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

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

gRPC — это эффективная реализация туннельного стиля (RPC), хорошо подходящая для распределенных систем. Он имеет SDK для многих языков и платформ, поэтому его можно широко использовать для связи между платформами и языками. gRPC очень быстр и эффективен, потому что он использует буферы протокола (protobufs) для сериализации и десериализации, стандарт HTTP/2 для оптимизированных двоичных передач и двунаправленную потоковую передачу, чтобы избежать (долгого) опроса и блокировки HTTP-вызовов.

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

Событийный стиль

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

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

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

Подведение итогов

Как мы рассмотрели, 5 стилей легли в основу популярных подходов и технологий, таких как REST, OpenAPI, HTTP, gRPC, GraphQL и Kafka. Самый важный урок, который нужно усвоить об этих 5 стилях API, заключается в том, что не существует лучшего стиля. Когда дело доходит до выбора стиля API, все сводится к следующим трем классам: проблема, потребители и контекст.

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

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

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

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

Связанные ресурсы

➔ Основы API.

➔ Стили API: SOAP, REST, RPC, GraphQL и другие.

Сообщество⤵️

🙋 Присоединяйтесь к сообществу Apache APISIX
🐦 Подпишитесь на нас в Twitter
📝 Найдите нас в Slack

Как выбрать правильный стиль и технологию API