HTTP. Краткие советы по использованию протокола

📌 URL идентифицирует ресурс. Вызов метода — не ресурс.
Не делайте так:
GET /?method=шарахнуть&to=Луна
Лучше так:
POST /шарахалка/?to=Луна

📌 URL состоит из схемы, хоста, пути, запроса и фрагмента. Путь — для иерархических ресурсов, запрос — для неиерархических и параметров операции. Фрагмент — для подчинённых ресурсов без URL.

Например, если у вас есть каталог котиков по породам, то породы — часть пути, города доставки — часть запроса, фрагмент – это якорь на странице:

http://nyashnye-kotiki.xxx/breeds/maine-coon/?deliver_to=Moscow#photo

📌 Обращение по HTTP — это применение метода (глагола) к URL. Результат должен соответствовать глаголу. Например, GET возвращает ресурс, DELETE удаляет его.

📌 Методы GET, HEAD, OPTIONS — безопасные. Они не изменяют состояние ресурса. Некоторые сетевые агенты могут вызывать их без вашего согласия.

📌 Методы GET и HEAD кэшируются по умолчанию, остальные — нет. Если вы хотите шарахнуть по Луне методом GET, то можете получить ответ из кэша и не шарахнуть на самом деле.

📌 Методы GET, PUT, DELETE идемпотентны, то есть возвращают один и тот же результат. PUT кладёт ресурс по URL-у, GET возвращает его, DELETE удаляет его. Метод HEAD возвращает только заголовки ресурса.

📌 POST используется, если у вас нет URL для операции. Например, если вы создаёте новое сообщение на форуме и не можете самостоятельно сгенерировать его ID.

POST /threads/php-rulezz/messages

Если вы повторите POST запрос — создастся дубликат сообщения. PUT можно повторять сколько угодно — результат не изменится. Это свойство называется идемпотентностью. Если клиент сам может сгенерировать ID, лучше использовать PUT:

PUT /threads/php-rulezz/messages/100500

📌 PUT может создавать или обновлять ресурсы целиком. PATCH может модифицировать ресурсы частично.

📌 Коды ответа нужны, чтобы клиент мог понять, что ему делать дальше.
3хх говорит, что нужно выполнить дополнительное действие.
4хх говорит, что клиент сделал что-то неправильно. В 4хх крайне рекомендуется включать информацию о том, что конкретно клиент сделал не так.
5хх говорит о том, что клиент всё сделал правильно — проблема на стороне сервера.

📌 Обычно при успешном выполнении операции сервер отвечает на GET — 200, на PUT — 201 Created (если ресурс создан) или 200 (ресурс обновлён), на DELETE — 204 (операция успешна, возвращать нечего), на POST — 200 или 201 (во втором случае в заголовке, обычно Location, указывается URL созданного ресурса).


📌 Работа с HTTP-статусами:

401 Unauthorized обязан сопровождаться заголовком WWW-Authenticate и подходит только для HTTP-аутентификации. Используйте 403 Forbidden для других случаев.

3xx статусы требуют дополнительного действия от клиента. Например, 304 Not Modified означает, что клиент должен взять ресурс из кэша.

404 статус может повторяться, так как ресурс может появиться позже. Если ресурса нет и не будет, используйте 410 Gone или 400.

📎 Материалы по теме
1. 15 тривиальных фактов о правильной работе с протоколом HTTP — Хабр, Яндекс
2. REST API Best Practices / Хабр
3. Best Practices in API Design — блог Swagger

Требования к требованиям, или свойства качественных требований

✅ Полнота. Требование содержит всю необходимую информацию, ничто не пропущено по соображениям «это и так всем понятно».

⛔️ Типичные проблемы:
➖ «пароли должны храниться в зашифрованном виде» - каков алгоритм шифрования?
➖ «экспорт осуществляется в форматы PDF, PNG и т.д.» — что мы должны понимать под «и т.д.»?
➖ «см. выше» вместо «см. раздел 123.45.b»

✅ Атомарность. Требование описывает одну ситуацию и не может быть разбито на части без потери смысла.

⛔️ Типичные проблемы:
➖ «кнопка “Restart” не должна отображаться при остановленном сервисе, окно “Log” должно вмещать не менее 20-ти записей о последних действиях пользователя» — в одном предложении описаны разные элементы интерфейса в разных контекстах
➖ «если пользователь подтверждает заказ и редактирует заказ или откладывает заказ, должен выдаваться запрос на оплату» — описаны три разных случая, и это требование стоит разбить на три отдельных во избежание путаницы
➖ «когда пользователь входит в систему, ему должно отображаться приветствие; когда пользователь вошел в систему, должно отображаться имя пользователя; когда пользователь выходит из системы, должно отображаться прощание» — все три ситуации должны быть описаны отдельно и более детально

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

⛔️ Типичные проблемы:
➖ «после успешного входа в систему пользователя, не имеющего права входить в систему…» — тогда как он успешно вошёл в систему, если не имел такого права?
➖ Противоречия между двумя и более требованиями, между таблицей и текстом, рисунком и текстом, требованием и прототипом и т.д. (например: «712.a Кнопка “Close” всегда должна быть красной» и «36452.x Кнопка “Close” всегда должна быть синей»

✅ Недвусмысленность. Требование формулируется ясно и однозначно, без использования жаргона, аббревиатур или расплывчатых выражений. Старайтесь избегать таких слов, как: много, мало, часто, редко, эффективно, большой, быстро, легко, несколько…

⛔️ Типичные проблемы:
➖ Использование терминов или фраз, допускающих субъективное толкование: «приложение должно поддерживать передачу больших объемов данных» — насколько больших?
➖ «В случае необходимости оптимизации передачи больших файлов система должна эффективно использовать минимум оперативной памяти, если это возможно»

✅ Выполнимость. Требование должно быть реализуемым в рамках бюджета и сроков разработки проекта.

⛔️ Типичные проблемы:
➖ «система поиска должна заранее предусматривать все возможные варианты поисковых запросов и кэшировать их результаты»
➖ «анализ договоров должен выполняться с применением искусственного интеллекта, который будет выносить однозначное корректное заключение о степени выгоды от заключения договора»

✅ Актуальность. Требование необходимо для успеха проекта и соответствует текущим условиям. Требование имеет приоритет, например, по MoSCoW.

⛔️ Типичные проблемы:
➖ Требование было добавлено «на всякий случай», хотя реальной потребности в нём нет
➖ Ошибки приоритета требования
➖ Требование устарело

✅ Прослеживаемость. Требования должны иметь атрибуты, позволяющие осуществлять трассировку требований и вносить изменения. Например: номер/ID, приоритет, владельца, ответственного

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

⛔️ Типичные проблемы:
➖ плохое оформление и ошибки в тексте;
➖ слишком глубокая детализация требования на уровне бизнес-требований или недостаточная детализация на уровне требований к продукту);
➖ «пользователь должен быть в состоянии отправить сообщение» — увы, мы не можем влиять на пользователя
➖ «в случае, если разрешение окна составляет менее 800x600…» — разрешение есть у экрана, у окна есть размер

📎 Статьи по теме
1. Требования (Requirements) — QA_Bible
2. Критерии качества требований — Наталья Чаусова
3. О критериях качества требований
— Art of Business Analysis

📄 Документы
Стандарт IEEE 830-1998 (SRS) на русском

#требования

Типы интеграции систем. Преимущества и недостатки

Выделяют 4 основных типа интеграции:
1. Файловая интеграция
2. Общая база данных
3. Удалённый вызов процедур
4. Обмен сообщениями

1️⃣ Файловая интеграция. Cистема А передает файл системе Б в определенном формате (например, CSV или XML). Файл с данными размещается в хранилище (например, файловом сервере), откуда другие системы могут его считать.

🟢 Преимущества

▫️Универсальность. Файлы поддерживаются любой операционной системой и языком программирования

▫️Простота. Просто закинули данные в файлик и готово

🔴 Недостатки

▪️Скорость. Обмен данными через файлы может быть медленным и приводить к рассинхронизации данных.

▪️Ненадежность. Нет гарантии, что файл дойдет до целевой системы и будет корректно обработан.

2️⃣ Общая база данных. Система А размещает свои данные в общей БД, из которой система Б может спокойно читать.

🟢 Преимущества

▫️Высокая скорость. Нет нагрузки на сеть. Данные доступны для чтения сразу после их записи в общую БД

▫️Единый формат данных и их целостность

🔴 Недостатки

▪️Высокая связанность. Любое изменение в схеме общей базы данных требует согласования всех интегрируемых приложений.

▪️Сложность проектирования. БД общая, схема БД общая. Нужно учесть особенности всех систем, а это очень трудоёмко и долго.

▪️Точка отказа. Если БД выйдет из строя, то конец всему.

3️⃣ Удалённый вызов процедур, или интеграция через API. Система А удаленно вызывает метод системы Б, передавая туда нужные параметры. Самые популярные способы реализовать этот подход: REST, SOAP, GraphQL и gRPC и т.д.

🟢 Преимущества

▫️Гибкость. Разработка и развертывание сервисов может быть выполнена независимо и быстро, без влияния на другие сервисы.

▫️Инкапсуляция. Данные и логика их обработки скрыты внутри удаленной процедуры, что повышает безопасность и целостность данных.

▫️Масштабируемость. Каждый сервис может быть масштабирован по отдельности в зависимости от нагрузки и потребностей.

🔴 Недостатки

▪️Контракты. Вызывающая система должна знать контракт вызываемой системы, а также ее доступность и адрес. Любое изменение в API может потребовать изменения в вызывающей системе.

▪️Сложность интеграции и эксплуатации. Распределение логики и данных по нескольким сервисам может затруднить координацию и мониторинг интеграционного решения.

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

4️⃣ Обмен сообщениями. Это асинхронный способ взаимодействия, при котором система А формирует сообщение и кладёт его в очередь. Система Б читает это сообщение и выполняет определённую логику. К этому способу относятся брокеры очередей сообщений (например, Kafka или RabbitMQ) и шины данных (ESB).

🟢 Преимущества

▫️Слабая связанность. Компоненты не нуждаются в знании друг о друге, они общаются только через брокер сообщений. Это повышает гибкость и масштабируемость

▫️Гарантированная доставка данных. Брокер сообщений может хранить и пересылать сообщения до тех пор, пока они не будут доставлены получателю. Это повышает надежность интеграционного решения.

▫️Масштабируемость. Сравнительно легко: просто добавляем больше ёмкости в наш брокер

▫️Асинхронность. Система А не должна ждать ответа от системы Б и может продолжать работу. Не требуется одновременной доступности обоих систем.

🔴 Недостатки

▪️Сложность интеграции и эксплуатации. Разработка и поддержка интеграционного решения требует знания и управления брокером сообщений, его коннекторами, форматами и правилами обмена сообщениями.

▪️Производительность. Обмен сообщениями может быть менее эффективным, чем прямой вызов, из-за сетевых затрат и дополнительной обработки сообщений брокером.

▪️Трудности согласования данных. Обмен сообщениями может приводить к рассинхронизации данных между системами из-за асинхронности.

В следующем посте поговорим о критериях выбора типа интеграции.

📎 Материалы по теме
1. Шаблоны интеграции корпоративных приложений — книга Хопа и Вульфа
2. Интеграции IT систем и при чем тут бар? — статья на Хабре

#интеграции

❓Как выбрать тип межсистемной интеграции

В предыдущем посте мы рассмотрели 4 типа интеграции систем. Настало время подумать над тем, какой способ лучше и в каких случаях. Вопросы выбора конкретного способа реализации, например, REST vs SOAP, будет рассмотрен в других постах.

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

1️⃣ Периодичность межсистемного взаимодействия. Как часто системы должны взаимодействовать? Отчего это зависит? Периодичность может быть следующей:
• По расписанию: система Б получает сведения из системы А раз в определенный период времени (минута, час, сутки и пр.).
• По событию: передача данных и удаленные вызовы функций выполняются при наступлении какого-то события в одной из систем или внешнем мире.
• По запросу: по явному запросу пользователя или другой системы.

2️⃣ Допустимая задержка обработки данных. Это время, которое проходит с момента появления данных в источнике до их получения приемником. Если данные нужно обрабатывать в реальном времени или с минимальной задержкой, то подходят технологии потоковой передачи, такие как gRPC

3️⃣ Степень связанности и зависимости систем. Чем сильнее системы связаны и зависят друг от друга, тем выше требования к согласованности и актуальности данных.

4️⃣ Степень изменчивости и динамичности систем. Чем чаще и сильнее системы меняются и развиваются, тем выше требования к гибкости и масштабируемости интеграции. Мы не можем использовать в таком случае единую БД, так как невозможно менять схему данных настолько часто, насколько это необходимо.

6️⃣ Масштабируемость. Это способность системы к росту путем увеличения количества вычислительных узлов (серверов). Масштабируемость зависит от балансировки нагрузки и пропускной способности технологии. Например, Kafka может обеспечить высокую пропускную способность и автоматическую балансировку нагрузки при передаче большого количества сообщений. Также важно учитывать количество источников и приемников данных, которые должны быть подключены к системе интеграции.

7️⃣ Возможность всех участвующих систем использовать выбранный тип интеграции. Не секрет, что разные приложения могут быть реализованы в разных архитектурных стилях и парадигмах разработки. Если мы выбираем способ файловой интеграции, то мы должны быть уверены, что интегрируемые системы умеют работать с предоставляемыми форматами.

Итого

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

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

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

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

💬 Пишите в комментариях, как вы определяете, какой тип интеграции нужно использовать👇

📎 Материалы по теме
1. Шаблоны интеграции корпоративных приложений — книга Хопа и Вульфа
2. 7 главных требований к интеграции ИС, чтобы определить решение — BABOK School
3. Типы системной интеграции
4. Базовое проектирование и разработка требований к интеграции систем (для начинающих аналитиков)
5. Интеграции IT систем и при чем тут бар?

#интеграции

В качестве дополнения сравнение видов (не путать с типами) интеграций. Типов в этой таблице всего 2: удалённый вызов процедур (первые 4) и обмен сообщениями (последние 2)

WebSocket: что это, когда следует использовать и какие преимущества дает

WebSocket — это технология, которая позволяет клиенту установить двухстороннюю («дуплексную») связь с сервером. Это означает, что он может одновременно и получать, и передавать информацию. Веб-сокет делает это множество раз в одном открытом соединении. В этом и заключается его основное преимущество по сравнению с традиционным HTTP, который является однонаправленным.

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

Механизм работы WebSocket

Физически WebSocket представляет собой протокол поверх TCP-соединения, как и HTTP (см. модель OSI).

1️⃣ Для установления соединения веб-сокет применяет метод открывающего рукопожатия. Он заключается в том, что клиент предваряет отправку/получение сообщений предварительным запросом, в котором клиент и сервер «договариваются» использовать веб-сокеты. Запрос отправляется на ws: или wss:: URI (аналог http или https).

2️⃣ Если сервер устанавливает соединение WebSocket, то сервер отправляет ответ об успешном рукопожатии. На это указывает HTTP-код 101 Switching Protocols.

3️⃣ После установления соединения протокол переключается с HTTP на WebSocket. Под капотом у нас остаётся TCP, который является двунаправленным протоколом. Веб-сокеты могут отправлять любые данные, даже очень большие, например, изображения. Для этого данные разбиваются на части, называемые фреймами. Каждый фрейм имеет заголовок, в котором указана информация о данных, такая как их размер и тип. Также заголовок содержит флаг, который показывает, является ли фрейм последним или нет.

4️⃣ Сервер может открывать несколько соединений WebSocket с несколькими клиентами или даже с одним и тем же клиентом. При этом сервер может отправить сообщение одному, нескольким или всем этим клиентам сразу.

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


✅ Когда использовать WebSocket

WebSocket подходит, когда нужны обновления данных в реальном времени и возможность доставлять сообщения клиенту без постоянных запросов (например, фондовые биржи, игровые приложения, чаты, IoT).


❌ Когда не стоит использовать WebSocket

1. Когда нужно получить неизменные данные, которые извлекаются только один раз, чтобы обработать их приложением, лучше использовать протокол HTTP, а не WebSocket.

2. Когда не нужно сохранять соединение в течение определенного времени или повторно использовать одно соединение для передачи данных. Например, ситуации, когда сервер должен отдать все данные для формы одним ответом.

📎 Материалы по теме
1. RFC 6455 - The WebSocket Protocol
2. WebSocket: что это, когда следует использовать и какие преимущества дает
3. Что такое веб-сокеты и как они вообще работают
4. WebSocket: смотрим как работает за кулисами
5. Асинхронный веб, или Что такое веб-сокеты

#интеграции

Применение UML 2.0 и шаблонов проектирования. Введение в объектно-ориентированный анализ, проектирование и интеративную разработку (3-е издание, 2004)
Автор: Крэг Ларман

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

Подробно описаны шаблоны GRASP. GoF шаблоны описаны поверхностно - постольку поскольку они необходимы в контексте книги. UML тоже описывается живо

#проектирование #интеграции

Нам нужно больше менеджеров

▶️ Подборка бесплатных вебинаров по основам интеграции систем

1. Как описывать требования к интеграции информационных систем? Ольга Пономарева

2. Введение в интеграции информационных систем · Татьяна Сальникова

3. Наталья Косинова. Мастер-класс: Интеграция информационных систем

4. Проектирование интеграционного взаимодействия между системами

5. Что такое хорошая интеграция / Максим Цепков

6. Межсервисные интеграции. Что может пойти не так? — Руслан Артамонов, Тинькофф

7. Геннадий Круглов. Доменно-ориентированный подход к интеграции

8. Обзор паттернов интеграции микросервисов

9. Плейлист по интеграции от Systems Education (20 видео)

Пересылайте коллегам 😊

#интеграции #подборка

Интеграция через API. Кратко

API (Application Programming Interface) — это набор способов и правил, по которым можно выполнять определённые действия с системой (например, получить данные или выполнить с ними какое-либо действие). Такой набор правил называют контрактом. Система как бы говорит: «ко мне можно обращаться так и так, я обязуюсь делать то и это».

Если систему рассматривать как чёрный ящик, то API — это набор «ручек», которые доступны пользователю данного ящика и которые он может вертеть и переключать.

Подходы к проектированию API

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

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

Интеграцию через API стоит использовать в тех случаях, когда:

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

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

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

Однако интеграция через API также имеет некоторые недостатки:

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

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

🔻Зависимость. API может быть недоступен или работать медленно из-за сетевых проблем или перегрузки системы. Поэтому необходимо иметь стратегию обработки сбоев и отказов API.

Какие бывают API:

🌟 SOAP: часто используется в корпоративных системах. Например, он может быть встроен в старые версии CRM-систем или в банковских приложениях.

🌟 REST: очень популярен в современных веб-приложениях. Под этот тип API, например, работают большинство публичных API таких сервисов как Twitter, GitHub или Stripe.

🌟 GraphQL: используется, когда требуется гибкость в выборе данных для запроса и по одному эндпоину (URL) можно получить разные варианты ответов.

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

🌟 gRPC: разработанный Google для высокопроизводительных приложений, он может быть встроен, например, в облачных решениях или микросервисах.

Другие способы интеграции описаны здесь. В следующих постах разберём REST.

📎 Материалы по теме
1. Что такое API? — статья от Amazon
2. Что такое API — статья от Doka

📖 Книги
1. Сергей Константинов. API
2. Арно Лоре. Проектирование веб-API
3. Web API Design: The Missing Link — небольшая книга от Google о проектировании API в REST стиле

▶️ Видео
1. Что такое API — Merion Academy
2. API для начинающих. Пример VK — Marlin
3. Как аналитику спроектировать свой REST API // Демо-занятие курса «Специализация «Системный аналитик»
4. API: под каким углом на них смотреть — доклад c конференции Analyst Days от Мелеховой Анны, Лаборатория Касперского

👍 Примеры открытых API
1. API ВКонтакте — можно потыкать ручками через веб-интерфейс
2. API DaData
3. Пример API Swagger

#api #интеграции

REST. Краткий обзор

REST (REpresentational State Transfer) – это архитектурный стиль, набор принципов проектирования, позволяющий добиться определённых свойств системы, таких как:
✹ Производительность
✹ Масштабируемость
✹ Гибкость к изменениям
✹ Отказоустойчивость
✹ Простота поддержки

🔹REST — это не протокол. Он не определяет правила о том, как мы должны передавать запросы, какая у них должна быть структура, что мы должны возвращать в ошибках. В качестве протокола использует REST HTTP.

🔹REST API (RESTful API) – это API, которые соответствует принципам REST.

🔹В архитектурном стиле REST нет ограничений по формату сообщений. REST API могут поддерживать любой формат сообщений, например XML, JSON, CSV, HTML и др.

🔹REST фокусируется на ресурсах, доступ к которым осуществляется через URL.

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

🔹Ресурс имеет свой адрес (URI), по которому его можно найти и запросить.

🔹HTTP-глаголы — это действия, которые можно выполнить над ресурсом. Например:
GET /schedule/speech/id413 — получить информацию об объекте с идентификатором 413

Принципы REST

1️⃣ Клиент-серверная архитектура – разделение зон ответственности между клиентом (кто использует API) и сервером (кто предоставляет API).

Преимущества:
+ Масштабируемость. Если растёт нагрузка на сервер, мы можем добавить ещё серверы
+ Простота поддержки и гибкость изменений. Если нам нужно внести изменения, мы можем сделать это на сервере, а клиент будет видеть изменения без каких-либо доработок на своей стороне.

Недостатки:
– Единая точка отказа в виде сервера.
– Увеличение нагрузки на сервер и сеть. Так как клиент будет совершать меньше каких-либо действий самостоятельно, вырастет количество запросов между клиентом и сервером.

2️⃣ Stateless – сервер не должен хранить у себя информацию о сессии с клиентом. Всю необходимую информацию для обработки клиент должен передавать в запросе. Сервер не может знать что-либо о предыдущих запросах от этого клиента.

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

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

3️⃣ Кэширование
В оригинале это говорит о том, что каждый ответ сервера должен иметь пометку, можно ли его кэшировать. Кэширование снижает нагрузку на серверы и ускоряет получение ответа для клиента.
Однако это может быть достаточно сложно в реализации. Нужно учитывать, что если отдаём какие-то данные, которые сохранили раньше, то они могли устареть

4️⃣ Единообразие интерфейса. HATEOAS
Все запросы API к одному и тому же ресурсу должны выглядеть одинаково, независимо от того, откуда поступает запрос.
Hypermedia as the Engine of Application State (HATEOAS) — одно из ограничений REST, согласно которому сервер возвращает не только ресурс, но и его связи с другими ресурсами и действия, которые можно с ним совершить. Например, если мы запрашиваем информацию о книге с помощью GET /books/1, то сервер может вернуть действия, которые можно сделать с книгой, например, добавить в корзину.

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

6️⃣ Код по требованию
Передача исполняемого кода от сервера клиенту. Это позволяет клиенту стать гибче

📎 Материалы
1. REST, что же ты такое? — статья и вебинар от Systems Education
2. Что такое REST API? — IBM
3. Бесплатный курс по документированию REST API
4. Серия видео Всё о REST API

#api #интеграции

Ликбез по понятиям: REST, API, HTTP

В чём разница между REST и API?

API – это набор ручек (методов), с помощью которых мы можем делать определённые действия с внешней системой. Система для нас чёрный ящик, мы знаем только, какие методы мы можем вызвать, по каким форматам передавать запросы и какие мы получим в результате. То есть, грубо говоря, API отвечает на вопрос “что”.

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

В чём разница между HTTP и REST?

HTTP – это протокол, который описывает, как происходит обмен данными по сети. HTTP определяет структуру запросов и ответов, набор допустимых методов, форматов сообщений, заголовков и так далее.

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

Может ли REST не использовать HTTP?

Да, может, но зачем? С одной стороны, REST не говорит, что нужно обязательно использовать HTTP. С другой стороны, HTTP специально спроектирован под REST. Более того, создатель REST и HTTP – это один и тот же человек, Рэй Филдинг.

Можно ли использовать HTTP без REST?

Можно, но зачем? Допустим, у нас есть CMS-система, которая предоставляет API для управления статьями. Если мы хотим удалить определённый объект, мы можем вызвать, например, такой метод: POST /delete_article, а в теле запроса передать id=1. Мы вызвали HTTP-метод POST, однако такой API не соответствует парадигме REST, то есть не является RESTful API. И вот почему.
Во-первых, он нарушает принцип единообразного интерфейса, так как не идентифицирует ресурс по его URI, а передает его идентификатор в теле запроса.

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

В парадигме REST мы должны были сделать примерно так: DELETE /articles/1/.

REST предполагает только JSON?

В архитектурном стиле REST нет ограничений по формату сообщений. REST API могут поддерживать любой формат сообщений, например XML, JSON, RSS, CSV, HTML и другие.

Какие бывают API помимо REST?

🔹 SOAP – протокол, который работает на XML и имеет стандарт. В отличие от REST, SOAP активно использует разные транспортные протоколы помимо HTTP, например, SMTP и FTP. А ещё SOAP не может использовать другой формат представления данных, кроме XML. Применяется в системах, где нужна жёсткая стандартизация, а также в legacy.

🔹 gRPC – это фреймворк для удалённого вызова процедур (RPC). Формат сообщений: бинарным Protocol Buffers, а протокол HTTP/2. Это позволяет преодолеть повысить производительность по сравнению с тяжеловесным SOAP и избыточной нагрузкой на сеть в REST. gRPC используется в высоконагруженных системах, где нужна высокая пропускная способность и производительность при низких требованиях к сети

🔹 GraphQL – это язык запросов для API, который позволяет клиентам получать только те данные, которые им нужны. Вместо вызова нескольких ресурсов в REST, в GraphQL мы можем отправить только один запрос к одной конечной точке, указав какие данные и в какой структуре нам нужны. Он уменьшает избыточность запросов и нагрузку на сеть. В качестве транспортного протокола использует HTTP.

🔹 WebSocket — это протокол, который позволяет клиенту установить двухстороннюю («дуплексную») связь с сервером. Это означает, что он может одновременно и получать, и передавать информацию. Веб-сокет делает это множество раз в одном открытом соединении. В этом и заключается его основное преимущество по сравнению с традиционным HTTP, который является однонаправленным.

💬 Вы можете писать свои вопросы в комментариях, мы дополним пост.

📎 Материалы по теме
1. HTTP. Что нужно знать аналитику
2. Как выбрать тип межсистемной интеграции
3. WebSocket: что это, когда следует использовать и какие преимущества дает

#api #интеграции

Виртуализация, контейнеризация и оркестрация

🔹 Виртуализация – это технология создания виртуальных машин на одном физическом сервере. Такие виртуальные машины (ВМ) полностью изолированы друг от друга: на них можно ставить разные операционные системы.

Виртуализация работает так:
1. На физический сервер ставится ОС и гипервизор – специальное ПО для распределения вычислительных ресурсов между ВМ
2. Создаются виртуальные машины, при этом на каждую ВМ устанавливается ОС


🔸 Контейнеризация — метод, с помощью которого код упаковывается в единый исполняемый файл вместе с библиотеками и зависимостями. Такой файл называют контейнером. Контейнер не зависит от настроек основной операционной системы и может работать на любой платформе или в облаке. Чаще всего для контейнеризации используется Docker.

Контейнеризация работает так:
1. На физический сервер ставится ОС
2. Формируется образ контейнера – представление, в которое упаковывается код со всеми зависимостями
3. Контейнер распаковывается на сервере и использует ядро ОС сервера. Поэтому он не требует установки отдельной ОС.

Назначение контейнеризации

1️⃣ Решается проблема с зависимостями в разных окружениях. Отлаженное на одном компьютере приложение можно легко развернуть на другом, ведь контейнер содержит все необходимые зависимости.

2️⃣ Использование в микросервисной архитектуре. Контейнеры хорошо подходят для приложений на основе микросервисов: можно проверить работоспособность каждого контейнера, ограничить каждую службу определенными ресурсами, запускать и останавливать их независимо друг от друга.

3️⃣ Контроль ресурсов и снижение нагрузки на систему благодаря тому, что каждый контейнер не содержит образ ОС.

4️⃣ Изоляция ошибок. Выход из строя одного контейнера не влияет на дальнейшую работу других контейнеров.


Виртуальные машины vs контейнеры

🔹 Виртуальная машина (ВМ) — операционная система (ОС), которая развернута внутри другой операционной системы. ВМ имеет свое ядро и некоторые обособленные ресурсы.

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

🔹 Виртуальная машина фактически представляет полноценную ОС с ядром, что требует больше аппаратных ресурсов (объемы оперативной памяти и хранилища, процессорные мощности).

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

🔹 Виртуальные машины могут запускать любое ядро операционной системы независимо от основной операционной системы. Допустим, если на сервере Linux, то виртуальная машина может быть Windows.

🔸 Контейнер должен быть совместим с ядром ОС сервера. Допустим, если на сервере Linux, то и контейнер должен использовать Linux.


Оркестрация

Оркестрация – автоматизация управления контейнерами. Например, если контейнер выходит из строя, оркестратор запустит другой контейнер.

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

Функции оркестратора

1️⃣ Управление контейнерами на нескольких физических серверах одновременно
2️⃣ Оптимизация ресурсов используемого оборудования
3️⃣ Автоматическое развертывание и обновления приложений
4️⃣ Подключение и добавление хранилищ для запуска приложений с отслеживанием состояния
5️⃣ Масштабирование контейнеров на лету

📎 Материалы по теме
1. Документация Docker
2. Документация Kubernetes
3. Контейнеризация приложений: что это такое и когда стоит использовать
4. Виртуализация и контейнеризация: обзор технологий и в чем разница
5. Что такое контейнеризация — Yandex Cloud
6. Контейнеризация понятным языком — Интервью с System Engineers (текст)
7. Docker и Kubernetes — чем отличаются технологии контейнеризации

#инфраструктура #оркестрация #контейнеризация #виртуализация

REST in Practice: Hypermedia and Systems Architecture (2010)
Авторы: Ian Robinson, Jim Webber, Savas Parastatidis

Язык: английский.

Целевая аудитория: начинающие разработчики.

REST  -  это популярный архитектурный стиль взаимодействия компонентов распределённого приложения в сети. В настоящем руководстве авторы познакомят вас с основами построения и работы REST архитектуры, с основными HTTP методами, статус-кодами и популярными шаблонами проектирования бизнес-приложений.

В книге рассматриваются следующие темы:
✔️ основы REST;
✔️ CRUD операции;
✔️ популярные паттерны;
✔️ безопасность в сети и многое другое.

Преимущества:
➕ многочисленные примеры;
➕ подробные объяснения;
➕ примеры на C# и Java.

Недостатки:
➖ местами устарелый материал;
➖ раскрыты не все особенности REST.

#api #интеграции

📎 Подборка материалов по изучению REST

📄 Статьи
1. REST, что же ты такое? — статья и вебинар от Systems Education
2. Что такое REST API? — IBM
3. Базовые понятия REST API
4. Разработка web API — краткий перевод основных тезисов из брошюры «Web API Design. Crafting Interfaces that Developers Love» Брайана Маллоя
5. Лучшие практики разработки REST API: 20 советов
6. Как тестировать методы REST API
7. REST в реальном мире и практика гипермедиа

▶️ Видео и вебинары
1. REST, что же ты такое?! Понятное введение в технологию. Андрей Бураков
2. Андрей Бураков. REST, почему ты такой? Скрытые смыслы популярной парадигмы.
3. Серия коротких видео Всё о REST API
4. Как аналитику спроектировать свой REST API // Демо-занятие курса «Специализация «Системный аналитик»
5. Документация REST API / Артём Кузвесов (Ideco)

🎓 Курсы
1. Бесплатный курс по документированию REST API

📖 Книги
1. Арно Лоре. Проектирование веб-API
2. Сергей Константинов. API
3. REST in Practice: Hypermedia and Systems Architecture

➕ Другое
1. Шаблон документации REST API
2. Шаблон документации микросервисов от МТС

#api #интеграции #подборка

⚙️ Что нужно знать про асинхронные интеграции

Асинхронная интеграция – это такая интеграция, когда одна система отправляет сообщение другой и не ждет подтверждения или ответа, а продолжает работу. Наиболее частый способ реализации асинхронной интеграции – это очереди (брокеры) сообщений, такие как Kafka или RabbitMQ. Очереди сообщений позволяют передавать сообщения между компонентами распределенных приложений. Передавать сообщения в очереди можно с помощью API.

Зачем нужна асинхронная интеграция:

✅ Слабая связанность сервисов. Наиболее часто применяется паттерн "издатель-подписчик". Сервис-издатель публикует сообщения в очереди и далее судьбой сообщений не интересуется. Т.е количество подписчиков и алгоритм использования сообщений сервис-издатель никак не задевают. В любой момент времени сообщения может читать один подписчик, тысяча, миллион или даже вообще никто не читать.

✅ Легкость масштабирования. Архитектура "издатель-подписчик" позволяет нам в любой момент поменять архитектуру приложения, изменить количество микросервисов, но при этом не менять код сервиса(ов)-публикатора(ов). Сервисы-потребители, при этом никак не влияют на работу друг друга. Наоборот, это также работает: можно увеличить количество публикаторов и их логику, подписчики, при этом, разницы не почувствуют.

✅ Повышение надежности. Выход из строя одного из компонентов не сказывается на работе всей системы: при восстановлении он обработает сообщение, находящееся в очереди. Ваш веб-сайт по-прежнему может работать, даже если задерживается часть обработки заказа, например, из-за проблем с сервером БД или системой электронной почты. Правда, при этом очередь сама приобретает статус SPoF (Single Point Of Failure), поэтому необходимо заранее предусмотреть действия на случай ее аварийного отключения.

Когда асинхронное взаимодействие лучше не использовать:

⛔️ У вашего приложения простая архитектура и функции, и вы не ожидаете его роста. Важно понимать, что очереди сообщений — это дополнительная сложность. Эту систему также необходимо настраивать, поддерживать, осуществлять мониторинг ее работы и так далее. Да, можно использовать Managed-решение, но вряд ли это будет оправдано для небольших приложений. Добавление очередей должно упрощать архитектуру, а не усложнять ее.

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

❗️ Также стоит учесть:

1. Очередь – это ещё одна система, которую необходимо поддерживать и на которую нужны мощности.

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

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

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

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

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

▪️Производительность. Если система требует высокой производительности и параллельной обработки запросов, асинхронное взаимодействие может быть более эффективным.

📎 Полезные материалы
1. Асинхронная интеграция. Что это такое и как её дружить
2. Зачем нужны очереди сообщений в микросервисной архитектуре
3. Что такое очереди сообщений и почему они широко используются в распределенных системах?
4. Брокеры сообщений, или Как происходит взаимодействие в рамках распределённой инфраструктуры
5. Брокеры сообщений

Совсем скоро выложим подборку полезных материалов по асинхронной интеграции 😉

#интеграции #async

Очереди сообщений. Основные понятия

Очереди сообщений помогают справится с высокой нагрузкой, сокращают время ответа за счёт асинхронной обработки и предотвращает потерю информации при сбоях.

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

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

🔹 Компонент, который добавляет сообщение в очередь, называется производителем (Producer).

🔹 Компонент, который извлекает сообщение из очереди и обрабатывает его, называется потребителем (Consumer).

Очередь может использоваться несколькими производителями и потребителями одновременно.

Два подхода к обмену сообщениями

➡️ Метод Pull: потребитель периодически опрашивает очередь на наличие новых сообщений и извлекает их по одному или нескольким за раз.

⬅️ Метод Push: очередь уведомляет потребителя о поступлении нового сообщения и отправляет его ему. Этот метод реализует модель “Издатель/Подписчик” (Publisher/Subscriber), когда потребитель подписывается на определенный тип или тему сообщений и получает только те сообщения, которые ему нужны.

Типы гарантии доставки сообщений

1️⃣ At least once: производитель отправляет сообщение в очередь и ждет подтверждения от брокера. Потребитель извлекает сообщение из очереди и отправляет подтверждение о его обработке. Если производитель не получает подтверждения от брокера, он повторно отправляет сообщение. Сообщение будет обработано хотя бы один раз, но при этом возможны ситуации, когда одно и то же сообщение будет обработано несколько раз. Например, когда соединение прервется в момент отправки или получения подтверждения. Для предотвращения последствий дублирования сообщений необходимо, чтобы компоненты были идемпотентными, то есть повторная обработка одного и того же сообщения не приводила бы к изменению состояния системы или ее данных. Также можно использовать уникальные id для сообщений и хранить список уже обработанных сообщений.

2️⃣ At most once: производитель отправляет сообщение в очередь и не ждёт подтверждения от брокера. Потребитель извлекает сообщение из очереди и не отправляет подтверждение о его обработке. Исключается возможность дублирования сообщений, но при этом сообщение может быть потеряно. Например, когда брокер не сможет сохранить сообщение в очереди или потребитель упадет во время обработки сообщения. Этот тип доставки подходит для тех случаев, когда двойная обработка сообщения может привести к серьезным проблемам, а потеря сообщения не является критичной.

3️⃣ Exactly once. Брокер гарантирует, что каждое сообщение будет доставлено и обработано ровно один раз, без потерь или дублирования. Этот тип доставки является самым желательным, но также самым сложным в реализации. Производитель отправляет сообщение в очередь и ждет подтверждения от брокера о его приеме. Потребитель извлекает сообщение из очереди и отправляет подтверждение об обработке.
В реальности полностью исключить вероятность потери или дублирования сообщений невозможно, поэтому этот тип доставки часто реализуется с некоторыми оговорками или допущениями.

Протоколы

🌐 AMQP — бинарный протокол, который проектировался для взаимодействия между различными вендорами. Основными особенностями AMQP является надежность и совместимость.

🌐 STOMP — простой текстовый протокол обмена сообщениями, который очень похож на HTTP и работает поверх TCP.

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

📎 Ссылки
1. Асинхронное взаимодействие. Брокеры сообщений
2. Очереди сообщений
3. Apache Kafka: основы технологии
4. Очереди сообщений в бэкенд-архитектуре: как построить надежную систему
5. Стратегии доставки и дедупликации сообщений

#интеграции #async

🖇 Подборка бесплатных материалов про асинхронную интеграцию и очереди сообщений

📄 Статьи
1. Зачем нужны очереди сообщений в микросервисной архитектуре — основы от VK Cloud
2. Асинхронная интеграция. Что это такое и как её дружить — обзорная статья на Хабре
3. Брокеры сообщений, или Как происходит взаимодействие в рамках распределённой инфраструктуры — статья на Хабре от Сбера
4. Брокеры сообщений — статья от Timeweb Cloud по основам брокеров сообщений
5. Стратегии доставки и дедупликации сообщений — статья на Хабре от OTUS

6. Асинхронное взаимодействие. Брокеры сообщений — чуть глубже по брокерам сообщений и немного про Кафку
7. Apache Kafka: основы технологии — от Слёрм
8. RabbitMQ для аналитика: практический ликбез — BABOK School
9. AMQP на примере RabbitMQ: как же «готовить кролика»? — простым языком о RabbitMQ

10. Соседняя очередь всегда движется быстрее — углубленная статья на Хабре про то, как устроены очереди и какие есть решения

11. Угнать за 5 миллисекунд: как мы наладили быструю доставку данных в сложной биржевой системе с помощью Tarantool — практический кейс проекта для Московской биржи
12. Как построить систему, способную выдерживать нагрузку в 5 млн rps — практический пример от Ozon. Тут будет про gRPC-прокси перед Кафкой


▶️ Видео и вебинары
1. Принципы и приёмы обработки очередей / Константин Осипов (то же, только статья)
2. Интеграция распределенных систем через обмен сообщениями — базовый вебинар
3. Реализация геораспределенной персистентной очереди сообщений / Василий Богонатов (Яндекс)
4. Микросервисы: Коммуникации через очередь сообщений
5. Очереди сообщений с RabbitMQ: что такое, когда нужно, какие проблемы решает
6. Как правильно выбирать очередь / Владимир Перепелица (Mail.Ru Group)
7. Битва брокеров сообщений: Kafka, RabbitMQ, SQS — Яндекс.Практикум


📖 Книги
1. Гайвин Рой. RabbitMQ для профессионалов — онлайн книга на русском
2. Emil Koutanov. Effective Kafka: A Hands-On Guide to Building Robust and Scalable Event-Driven Applications with Code Examples — одна из лучших книг по Кафке
3. Дилан Скотт, Виктор Гамов, Дейв Клейн. Kafka в действии — на русском
4. Понимание брокеров сообщений. Изучение механики обмена сообщениями посредством ActiveMQ и Kafka

Если у кого есть, чем поделиться - пишите в комментариях!

#интеграции #подборка #async