Памятка по проектированию системы: стили API — REST, GraphQL, WebSocket, Webhook, RPC/gRPC, SOAP

Это продолжение серии статей, в которых я кратко освещаю основные моменты конкретной темы проектирования системной архитектуры. Первую статью можно прочитать здесь

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

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

Различные стили архитектуры API

Наиболее распространенные стили дизайна API:

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

   
   

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

   
   

3. WebSocket — это протокол, обеспечивающий двустороннюю связь по TCP. Клиенты используют веб-сокеты для получения обновлений в реальном времени от серверных систем.

   
   

4. Webhook — это механизм, который позволяет одной системе уведомлять другую систему о конкретных событиях в режиме реального времени. Это определяемый пользователем обратный вызов HTTP.

   
   

5. RPC (gRPC) — это протокол, который одна служба может использовать для запроса процедуры/метода у службы, расположенной на другом компьютере в сети. Обычно он предназначен для высокоскоростной связи с малой задержкой.

   
   

6. SOAP — это протокол обмена структурированной информацией для реализации веб-сервисов. Он основан на XML и известен своей надежностью и функциями безопасности и в настоящее время считается устаревшим протоколом.

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

ОТДЫХ

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

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

Формат : XML, JSON, HTML, обычный текст.

Транспортный протокол : HTTP/HTTPS.

Ключевые понятия и характеристики

• Ресурс : В REST все является ресурсом. Ресурс — это объект с типом, связанными с ним данными, связями с другими ресурсами и набором методов, которые с ним работают. Ресурсы идентифицируются по их URI (обычно URL).

  
  

• Операции CRUD . Службы REST часто сопоставляются непосредственно с операциями CRUD (создание, чтение, обновление, удаление) над ресурсами.

  
  

• Методы HTTP . Системы REST используют стандартные методы HTTP:

  • GET: Получить ресурс.

  • POST: Создайте новый ресурс.

  • PUT/PATCH: обновить существующий ресурс.

  • УДАЛЕНИЕ: удалить ресурс.

    
    

• Коды состояния . API-интерфейсы REST используют стандартные коды состояния HTTP для обозначения успеха или неудачи запроса API:

  • 2xx – Признание и успех
    • 200 - ОК
    • 201 – Создано
    • 202 – Принято
  • 3xx — перенаправление
    • 301 - Переехал навсегда
    • 302 - Найдено
    • 303 - См. другое
  • 4xx — ошибка клиента
    • ошибка 400, неверный запрос
    • 401 – Несанкционированный
    • 403 - Запрещено
    • 404 Не Найдено
    • 405 - Метод не разрешен
  • 5xx — ошибка сервера

    • 500 - внутренняя ошибка сервера

    • 501 - Не реализовано

    • 502 Неверный шлюз

    • 503 Сервис недоступен

    • Ошибка 504 Время ответа сервера истекло

      
      

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

  
  

• Клиент-Сервер : REST основан на модели клиент-сервер. Клиент отвечает за пользовательский интерфейс и работу, а сервер отвечает за обработку запросов, обработку бизнес-логики и хранение данных.

  
  

• Кэшируемый : ответы сервера могут кэшироваться клиентом. Сервер должен указать, кэшируется ли ответ или нет.

  
  

• Многоуровневая система : клиент обычно не может определить, подключен ли он напрямую к конечному серверу или к посреднику. Промежуточные серверы могут улучшить масштабируемость системы, обеспечивая балансировку нагрузки и предоставляя общий кэш.

  
  

• HATEOAS: Hypermedia As the Engine Of Application Stat — это принцип веб-службы REST, который позволяет клиентам взаимодействовать с веб-приложением и перемещаться по нему, полностью основываясь на гипермедиа, динамически предоставляемом сервером в его ответах, обеспечивая слабую связь и возможность обнаружения.

Случаи использования

• Веб-сервисы . Многие веб-сервисы раскрывают свою функциональность через REST API, что позволяет сторонним разработчикам интегрировать и расширять свои сервисы.

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

• Одностраничные приложения (SPA) . SPA используют REST API для динамической загрузки контента без необходимости полного обновления страницы.

• Интеграция между системами. Системы внутри организации могут обмениваться данными и обмениваться ими с помощью REST API.

Пример

Запрос

ПОЛУЧИТЬ «/пользователь/42»

Ответ

 { "id": 42, "name": "Alex", "links": { "role": "/user/42/role" } }

ГрафQL

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

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

Формат : JSON

Транспортный протокол : HTTP/HTTPS.

Ключевые понятия и характеристики

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

• Система типов : API GraphQL организованы по типам и полям, а не по конечным точкам. Он использует строгую систему типов для определения возможностей API. Все типы, представленные в API, записаны в схеме с использованием языка определения схемы GraphQL (SDL).

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

• Резолверы : на стороне сервера резолверы собирают данные, описанные в запросе.

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

• Интроспективный : к серверу GraphQL можно запросить типы, которые он поддерживает. Это создает прочный контракт между клиентом и сервером, позволяя использовать инструменты и улучшать проверку.

Случаи использования

• Гибкие интерфейсы . Для приложений (особенно мобильных) с критической пропускной способностью необходимо минимизировать объем данных, получаемых с сервера.

• Агрегирование микросервисов . Можно добавить уровень GraphQL для агрегирования данных из этих сервисов в единый API, если у вас есть несколько микросервисов.

• Приложения реального времени . Благодаря своей системе подписки GraphQL может отлично подойти для приложений, которым нужны данные в реальном времени, таких как чат-приложения, спортивные новости в прямом эфире и т. д.

• API без версий . При использовании REST вам часто требуется обновлять версии API после внесения изменений. С GraphQL клиенты запрашивают только необходимые данные, поэтому добавление новых полей или типов не приводит к критическим изменениям.

Пример

Запрос

GET «/graphql?query=user(id:42){ name role { id name } }»

Ответ

 { "data": { "user": { "id": 42, "name": "Alex", "role": { "id": 1, "name": "admin" } } } }

Вебсокет

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

Формат : двоичный

Транспортный протокол : TCP

Ключевые понятия и характеристики

• Постоянное соединение . В отличие от традиционной модели запрос-ответ, WebSockets предоставляет полнодуплексный канал связи, который остается открытым, что позволяет обмениваться данными в реальном времени.

• Обновление рукопожатия : WebSocket запускается как HTTP-запрос, который затем обновляется до соединения WebSocket, если сервер его поддерживает. Это делается через заголовок «Upgrade».

• Кадры : после установления соединения данные передаются в виде кадров. Через эти кадры можно отправлять как текстовые, так и двоичные данные.

• Низкая задержка : WebSockets позволяют осуществлять прямую связь между клиентом и сервером без необходимости открытия нового соединения для каждого обмена. Это приводит к более быстрому обмену данными.

• Двунаправленный : и клиент, и сервер могут отправлять сообщения друг другу независимо.

• Меньше накладных расходов : после первоначального соединения для отправки кадров данных требуется меньше байтов, что приводит к меньшим накладным расходам и повышению производительности, чем многократное установление HTTP-соединений.

• Протоколы и расширения . WebSockets поддерживают подпротоколы и расширения, что позволяет использовать стандартизированные и пользовательские протоколы поверх базового протокола WebSocket.

Случаи использования

• Онлайн-игры : многопользовательские игры в реальном времени, в которых действия игроков должны немедленно отражаться на других игроках.

• Инструменты для совместной работы : такие приложения, как Google Docs, где несколько пользователей могут редактировать документ одновременно и видеть изменения друг друга в режиме реального времени.

• Финансовые приложения : платформы для торговли акциями, где цены на акции необходимо обновлять в режиме реального времени.

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

• Прямые каналы : новостные веб-сайты или платформы социальных сетей, где новые сообщения или обновления транслируются пользователям в прямом эфире.

Пример

Запрос

ПОЛУЧИТЕ «ws://сайт:8181»

Ответ

HTTP/1.1 101 Протоколы коммутации

Вебхук

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

Формат : XML, JSON, обычный текст.

Транспортный протокол : HTTP/HTTPS.

Ключевые понятия и характеристики

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

• Механизм обратного вызова . Вебхуки, по сути, представляют собой определяемый пользователем механизм обратного вызова. Когда происходит определенное событие, исходный сайт выполняет обратный вызов HTTP к URI, предоставленному целевым сайтом, который затем выполняет определенное действие.

• Полезная нагрузка : при срабатывании вебхука исходный сайт отправит данные (полезную нагрузку) на целевой сайт. Эти данные обычно имеют форму JSON или XML.

• В режиме реального времени : веб-перехватчики позволяют приложениям получать данные в режиме реального времени, что делает их более быстрыми.

• Настраиваемый : пользователи или разработчики обычно могут определить, о каких конкретных событиях они хотят получать уведомления.

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

Случаи использования

• Непрерывная интеграция и развертывание (CI/CD) : запуск сборок и развертываний при отправке кода или объединении запроса на включение.

• Системы управления контентом (CMS) : уведомление нижестоящих систем при обновлении, публикации или удалении контента.

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

• Интеграция с социальными сетями : получение уведомлений о новых публикациях, упоминаниях или других соответствующих событиях на платформах социальных сетей.

• IoT (Интернет вещей) : устройства или датчики могут запускать веб-перехватчики для уведомления других систем или служб о конкретных событиях или показаниях данных.

Пример

Запрос

ПОЛУЧИТЕ « https://external-site/webhooks?url=http://site/service-h/api&name=name »

Ответ

 { "webhook_id": 12 }

RPC и gRPC

RPC (удаленный вызов процедур) — это протокол, который позволяет программе выполнять процедуру или подпрограмму в другом адресном пространстве, обеспечивая бесперебойную связь и обмен данными между распределенными системами.

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

ПКП

Формат : JSON, XML, Protobuf, Thrift, FlatBuffers.

Транспортный протокол : Разный

Ключевые понятия и характеристики

• Определение : RPC позволяет программе вызвать выполнение процедуры (подпрограммы) в другом адресном пространстве (обычно на другом компьютере в общей сети). Это похоже на вызов функции, выполняемой на другой машине, отличной от машины вызывающей стороны.

• Заглушки : в контексте RPC заглушки — это фрагменты кода, созданные инструментами, которые позволяют локальным и удаленным вызовам процедур выглядеть одинаково. У клиента есть заглушка, которая выглядит как удаленная процедура, а у сервера есть заглушка, которая распаковывает аргументы, вызывает фактическую процедуру, а затем упаковывает результаты для отправки обратно.

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

• Нейтральность языка : многие системы RPC позволяют различным реализациям клиента и сервера взаимодействовать независимо от языка, на котором они написаны.

• Тесная связь : RPC часто требует, чтобы клиент и сервер знали вызываемую процедуру, ее параметры и тип возвращаемого значения.

Случаи использования

• Распределенные системы : RPC обычно используется в распределенных системах, где части системы распределены по разным машинам или сетям, но должны взаимодействовать так, как если бы они были локальными.

• Сетевые файловые системы : NFS (сетевая файловая система) является примером RPC, выполняющих файловые операции удаленно.

Пример

Запрос

 { "method": "addUser", "params": [ "Alex" ] }

Ответ

 { "id": 42, "name": "Alex", "error": null }

gRPC

Формат : Protobuf

Транспортный протокол : HTTP/2.

Ключевые понятия и характеристики

• Определение : gRPC — это платформа RPC с открытым исходным кодом, разработанная Google. Он использует HTTP/2 для транспорта, буферы протокола (Protobuf) в качестве языка описания интерфейса, а также обеспечивает аутентификацию, функции балансировки нагрузки и многое другое.

• Буферы протокола : это независимый от языка и платформы расширяемый механизм сериализации структурированных данных. С помощью gRPC вы определяете методы обслуживания и типы сообщений с помощью Protobuf.

• Производительность : gRPC разработан для обеспечения низкой задержки и высокой пропускной способности. HTTP/2 позволяет мультиплексировать несколько вызовов по одному соединению и снижает накладные расходы.

• Потоковая передача : gRPC поддерживает потоковую передачу запросов и ответов, что позволяет использовать более сложные случаи, такие как долгоживущие соединения, обновления в реальном времени и т. д.

• Сроки/тайм-ауты : gRPC позволяет клиентам указывать, как долго они будут ждать завершения RPC. Сервер может проверить это и решить, следует ли завершить операцию или прервать ее, если она, вероятно, займет слишком много времени.

• Подключаемый : gRPC предназначен для поддержки подключаемой аутентификации, балансировки нагрузки, повторных попыток и т. д.

• Языковая нейтральность : как и RPC, gRPC не зависит от языка. Однако с помощью Protobuf и инструментов gRPC легко генерировать клиентский и серверный код на нескольких языках.

Случаи использования

• Микросервисы : gRPC обычно используется в архитектурах микросервисов из-за его характеристик производительности и возможности легко определять контракты обслуживания.

• Приложения реального времени . Благодаря поддержке потоковой передачи gRPC подходит для приложений реального времени, где серверы передают данные клиентам в режиме реального времени.

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

Пример

 message User { int id = 1 string name = 2 } service UserService { rpc AddUser(User) returns (User); }

МЫЛО

SOAP , что означает Simple Object Access Protocol, представляет собой протокол обмена структурированной информацией для реализации веб-сервисов в компьютерных сетях. Это протокол на основе XML, который позволяет программам, работающим в разных операционных системах, взаимодействовать друг с другом.

Формат : XML

Транспортный протокол : HTTP/HTTPS, JMS, SMTP и др.

Ключевые понятия и характеристики

• На основе XML : сообщения SOAP форматируются в XML и содержат следующие элементы:

  • Конверт : корневой элемент сообщения SOAP, определяющий XML-документ как сообщение SOAP.

  
  

  • Заголовок : содержит любые необязательные атрибуты сообщения, используемые при обработке сообщения, либо в промежуточной точке, либо в конечной конечной точке.

  
  

  • Тело : содержит данные XML, составляющие отправляемое сообщение.

  
  

  • Fault : дополнительный элемент Fault, предоставляющий информацию об ошибках при обработке сообщения.

    
    

• Нейтральность : SOAP может использоваться с любой моделью программирования и не привязан к какой-то конкретной.

• Независимость : он может работать в любой операционной системе и на любом языке.

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

• Встроенная обработка ошибок : элемент Fault в сообщении SOAP используется для сообщения об ошибках.

• Стандартизированный : работает на основе четко определенных стандартов, включая саму спецификацию SOAP, а также связанных стандартов, таких как WS-ReliableMessaging для обеспечения доставки сообщений, WS-Security для безопасности сообщений и т. д.

Случаи использования

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

• Веб-службы . Многие веб-службы, особенно старые, используют SOAP. Сюда входят услуги, предлагаемые крупными компаниями, такими как Microsoft и IBM.

• Финансовые транзакции . Встроенная безопасность и расширяемость SOAP делают его хорошим выбором для финансовых транзакций, где целостность и безопасность данных имеют первостепенное значение.

• Телекоммуникации . Телекоммуникационные компании могут использовать SOAP для таких процессов, как выставление счетов, когда различные системы должны надежно взаимодействовать.

Пример

Запрос

 <?xml version="1.0"?> <soap:Envelope> <soap:Body> <m:AddUserRequest> <m:Name>Alex</m:Name> </m:AddUserRequest> </soap:Body> </soap:Envelope>

Ответ

 <?xml version="1.0"?> <soap:Envelope> <soap:Body> <m:AddUserResponse> <m:Id>42</m:Id> <m:Name>Alex</m:Name> </m:AddUserResponse> </soap:Body> </soap:Envelope>

Заключение

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