Также подготовили сравнение RabbitMQ vs Kafka в табличном виде
#сравнение

🫙 Основные понятия баз данных. Главное

Понимание принципов работы и основ проектирования БД – это основа всех hard skills для системного аналитика, а также и для бизнес-аналитика: BABOK упоминает технику моделирования данных как одно из наиболее востребованных умений бизнес-аналитика.

Следует различать БД и СУБД:

➖ База данных (БД) – структурированный набор данных, который хранится на сервере.
➖ Система управления базами данных (СУБД) – это ПО, которая позволяет управлять данными в БД: читать и изменять.

БД могут быть реляционными и нереляционными (подробнее см. пост).

🔹 Реляционные БД хранят информацию в виде таблиц. Между таблицами определяются связи (relations) – создаётся схема данных. Для манипулирования данными применяется специальный язык запросов – SQL. Реляционные БД применяются повсеместно, лучше всего подходят для поддержки транзакций или когда нужно поддерживать строгую структуру данных и соблюдать требования ACID (о них ниже). Примеры реляционных СУБД: MySQL, PostgreSQL, Oracle.

🔸 Нереляционные БД (NoSQL) – это все остальные виды БД, например, ключ-значение, графовые, временных рядов и другие. Все виды нереляционных БД объединяет одно – данные хранятся любым другим способом, кроме таблиц. Из альтернативного названия (NoSQL) Часто применяется там, где нужна высокая скорость (например, для кэширования), требуется работать с большими объёмами данных и обеспечивать лёгкость масштабирования. Примеры нереляционных СУБД: MongoDB, Redis, Cassandra.

Основные понятия реляционных БД

📌 Сущность (entity) – это объект, который имеет смысл в предметной области и может быть представлен в БД. Например, студент, книга, заказ и т.д. Сущности обычно соответствуют таблицам в реляционных БД.

📌 Атрибут (attribute) – это характеристика сущности, которая может быть измерена или описана. Например, сущность Книга имеет название, автора, год издания и т.д. Атрибуты обычно соответствуют столбцам в реляционных БД.

📌 Первичный ключ (primary key) – это атрибут или набор атрибутов, который однозначно идентифицирует каждую сущность в БД. Например, username в телеграме, id страницы ВК и т.д. Первичный ключ не может быть пустым или повторяться в рамках одной таблицы.

📌 Внешний ключ (foreign key) – это атрибут или набор атрибутов, который ссылается на первичный ключ другой сущности. Например, book_id в таблице Заказы ссылается на номер книги id в таблице Книги. Внешний ключ позволяет установить связь между сущностями и гарантировать соблюдение целостности данных. В данном примере с таблицей Заказы мы не можем поместить в столбец такой номер книги book_id, которого нет в таблице Книги – СУБД нам не позволит.

Транзакционность – важнейшее свойство реляционных БД

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

Все транзакции должны отвечать требованиям ACID:
1️⃣ Атомарность (atomicity) — транзакция является неделимым блоком и выполняется или полностью, или никак.
2️⃣ Согласованность (consistency) — завершенная транзакция сохраняет согласованность базы данных.
3️⃣ Изолированность (isolation) — параллельные транзакции не могут влиять друг на друга.
4️⃣ Устойчивость (durability) — никакой сбой в системе не может влиять на результат завершенной транзакции.

Следуя принципу ACID, БД будет целостна только тогда, когда она будет содержать все результаты успешных запросов, выполненных в транзакции. БД гарантирует, что в случае ошибки в транзакции, данные не будут изменены.

Про типы связей и нормализацию данных расскажем в следующих постах. Если вы хотите увидеть эти материалы поскорее, ставьте ⚡️

Ссылки на полезные материалы по основам БД в следующем посте👇

#бд

🖇 Подборка полезных материалов по основам баз данных
📣 Делитесь с коллегами

🎓 Бесплатные курсы
Наша подборка: список бесплатных онлайн-курсов по базам данных и SQL
+ курс по реляционным БД от Хекслет (теория бесплатно — кликайте на ссылку теория напротив каждой темы либо зарегистрируйтесь)
+ курс Введение в базы данных от ВШЭ и Политеха
+ видеокурс на YouTube Реляционные базы данных. SQL
+ ещё курс лекций на YouTube от Института программных систем

📑 Статьи (теория)
1. Основы баз данных для бизнес-аналитика: краткий ликбез — Babok School
2. Реляционные базы данных — база знаний Yandex Cloud
3. Что такое ACID в базах данных? — подробная статья
3.1 Требования ACID на простом языке
4. О транзакционности
Виды баз данных. Большой обзор типов СУБД — про виды нереляционных БД
5. Руководство по проектированию реляционных баз данных

📝 Статьи (практика)
1. Как выбрать СУБД для работы с большими данными?
2. Как получить информацию о структуре БД для документации
3. Инструкция: как посмотреть ER-модель готовой БД

⏯ Видео и вебинары
1. Основы реляционных баз данных и языка SQL
2. Что такое SQL и реляционные базы данных

📚 Книги
1. Большая подборка книг по БД на любой вкус
2. Основы проектирования БД от ИТМО (73 стр.)
3. Роб Корон. Базы данных. Проектирование, реализация и сопровождение. Теория и практика — огромный талмуд, но основательно

🕹 Онлайн-тренажёры по SQL
🔹 Karpov.courses — тренажёр с исчерпывающими заданиями
🔹 SQL Academy — онлайн тренажер с упражнениями по SQL
🔹 Learn DB — аналог первого
🔹SQL-EX — упражнения и Интерактивный учебник по SQL;
🔹 SQLBolt — пошаговый интерактивный учебник (уроки + упражнения)
🔹 Solve SQL | HackerRank — платформа для практики и изучения языков программирования
🔹 SQL Fiddle — эмулятор написания SQL-запросов, позволяет практиковаться на разных типах СУБД (MySQL, PostgreSQL, SQLite, MS SQL Server)
🔹 SQL Tutorial — справочник с множеством примеров и упражнений

А ещё коллеги из Systems.Education и NextWay собрали большой каталог ссылок на тему баз данных и анализа данных.

#подборка #бд #sql

Типы связей в БД. Нормализация

В предыдущих постах мы коснулись основных понятий БД и собрали ссылки на полезные материалы. Пора написать про типы связей и нормализацию.

Сущности (таблицы) в БД не существуют изолированно друг от друга: между ними устанавливаются связи. Для организации связи используются внешние ключи. Например, таблица Заказы может быть связана с таблицей Книги через поле book_id в таблице Заказы, значения которого берутся из поля id таблицы Книги.

Связи между таблицами бывают следующих типов:

1️⃣ Один-к-одному (one-to-one) – одной записи в родительской таблице соответствует одна запись в дочерней. Например, человек может иметь только один паспорт и паспорт может принадлежать только одному человеку. Этот вид связи используют, если не хотят, чтобы таблица БД "распухала" от второстепенной информации, однако для чтения связанной информации в нескольких таблицах приходится производить ряд операций чтения вместо одной, когда данные хранятся в одной таблице.

2️⃣ Один-ко-многим (one-to-many) – одной записи родительской таблицы может соответствовать несколько записей дочерней. Например, преподаватель может вести несколько курсов, но каждый курс может вести только один преподаватель. Это самая классическая связь для реляционных БД.

3️⃣ Многие-ко-многим (many-to-many) – каждый экземпляр одной сущности может быть связан с несколькими экземплярами другой сущности и наоборот. Всякую связь "многие–ко–многим" в реляционной базе данных необходимо заменить на связь "один–ко–многим" (одну или более) с помощью введения дополнительных таблиц. Например, студент может записаться на несколько курсов и каждый курс может иметь несколько студентов. Следует добавить новую таблицу Расписание, которое будет связывать таблицы Студенты и Курсы.


Нормализация данных

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

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

Нормализация базы данных выполняется с помощью набора правил. Они называются нормальными формами. Выделяют около 8-ми нормальных форм, но на практике используются первые три. Каждая следующая НФ дополняет предыдущую.

Три нормальные формы:

1️⃣ Информация в каждом поле таблицы является неделимой и не может быть разбита на подгруппы: нет повторяющихся строк и все атрибуты атомарны (простые типы данных)

2️⃣ У таблицы есть первичный ключ, а все остальные поля зависят от всего первичного ключа, но не от его части (если первичный ключ составной)

3️⃣ Все неключевые атрибуты зависят только от первичного ключа и не зависят друг от друга


📎 Материалы

📑 Статьи
1. Разбираем базы данных и язык SQL. (Часть 5 — связи и джоины) — статья на JavaRush про связи в БД с примерами
2. Связи между таблицами SQL — обзор Максима Гритчина про виды джойнов и связей в БД
3. Простыми словами про нормализацию + аудио- видео- ряд
4. Что такое нормализация базы данных — от merion academy
5. Как привести данные в форму — блог Практикума

⏯ Видео
1. Моделирование данных за 9 минут — про типы связей
2. Базы данных. 1,2,3 нормальные формы (10 минут)
3. Нормальные формы базы данных. Три нормальных формы, нормализация и денормализация БД

#бд

DAMA-DMBOK: Свод знаний по управлению данными. Второе издание [2020] на русском

Главная задача книги — определить набор руководящих принципов и описать их применение в функциональных областях управления данными. Издание всесторонне описывает проблемы, возникающие в процессе управления данными, и предлагает способы их решения. В нем подробно описаны широко принятые практики, методы и приемы, функции, роли, результаты и метрики.

Задачи "DAMA-DMBOK2":
● Выработка общепринятого согласованного представления об областях знаний по управлению данными (выделено 11 таких областей);
● Определение руководящих принципов управления данными;
● Предоставление стандартных определений для наиболее часто используемых понятий (общих и по областям знаний);
● Обзор общепринятых лучших практик, широко распространенных методов и методик, а также наиболее известных альтернативных подходов;
● Краткий обзор общих организационных и культурных вопросов;
● Уточнение границ сферы управления данными.

#бд #свод_знаний

🆚 gRPC vs REST: сравнение по пунктам

Ранее мы уже делали посты про REST и SOAP, а также сравнивали их по пунктам. А
в предыдущем посте мы рассмотрели основные аспекты gRPC. Теперь сравним его с REST, чтобы понять, когда что использовать для проектирования API.

Protobuf вместо JSON / XML

🔹 Обычно в REST используются форматы сообщений JSON / XML / YAML. Такой формат удобен и понятен для человека, но обратная сторона этого – скорость передачи сообщений

🔸 В gRPC использует двоичный формат обмена сообщениями Protobuf . За счёт сжатия и бинарной сериализации это позволяет увеличить скорость передачи сообщений в разы. Обратная сторона – формат Protobuf нечеловекочитаем

HTTP/2 вместо HTTP 1/1

🔹 Обычно в REST API используются HTTP 1/1, который предполагает взаимодействие по типу запрос-ответ. Это означает, что когда микросервис получает несколько запросов от более чем одного клиента, он должен обслуживать их по одному, что замедляет работу всей системы.

🔸 gRPC использует HTTP/2 и позволяет группировать запросы в пакеты и, самое главное, устанавливать двунаправленное соединение. Теперь, когда микросервис получает несколько запросов от более чем одного клиента, он может обслуживать их одновременно и отдавать ответы в режиме реального времени. Клиенту не нужно отправлять несколько запросов последовательно, открывая для каждого запроса новое TCP-соединение (см. модель OSI)

gRPC строго определяет контракт

🔹 В REST не даёт чёткого определения того, как должны быть описаны контракты. Да, можно использовать OpenAPI и Swagger для генерации кода, но на практике такое встречается нечасто, в том числе в силу объективных причин. Обычно наоборот: из кода генерируют сваггер и вставляют в Confluence. У кого есть опыт на этот счёт, пишите в комменты!

🔸 В gRPC есть строгое определение того, как должны выглядеть запросы и ответы. Контракт определяется в файле .proto, который описывает типы сообщений и сервисы, которые предоставляются. Затем proto-файлы клиент может преобразовать в заглушки с помощью готовых плагинов кодогенерации от Google для разных языков программирования

gRPC API дольше реализовывать

🔹 REST – это мейнстрим и огромное коммьюнити, лёгкость и простота. Существует множество фреймворков и библиотек, которые упрощают разработку и тестирование REST API.

🔸 gRPC требует гораздо более серьёзного погружения и менее распространён. Для создания gRPC API необходимо использовать специальный формат данных Protobuf и определять контракты в файлах .proto. Также нужно учитывать особенности HTTP/2 и потоковой передачи данных.

Итак, что выбрать

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

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

2️⃣ Системы где используется несколько языков программирования благодаря поддержке генерации собственного кода для широкого спектра языков разработки

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

4️⃣ Сети с низким энергопотреблением и низкой пропускной способностью, например, IoT: использование gRPC сериализованных сообщений Protobuf обеспечивает легкий обмен сообщениями, большую эффективность и скорость по сравнению с JSON.

Статьи
1. gRPC vs REST, что выбрать для нового сервера? — Хабр. Есть также видео
2. Сравнение от Amazon

Видео
1. gRPC vs REST, что выбрать для нового сервера? — видео о статье 1
2. gRPC vs REST. Плюсы и минусы на примере реального проекта

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

И как всегда для удобства сравнение gRPC vs REST картинкой
📣 делитесь с коллегами

#сравнение

🏆 Лучшие практики проектирования API

В названиях путей к эндпоинтам используем имена, а не глаголы
В метода HTTP-запроса уже содержится глагол. Ставить глаголы в названиях путей к конечной точке API не добавит никакой ценной информации
✅ GET /v1/articles/{id}
❌ POST /v1/get-article/{id}

Коллекции называем существительными во множественном числе
Соблюдаем единообразие интерфейсов (принцип REST №4)
✅ GET /v1/articles/{id}
❌ GET /v1/article/{id}

Иерархия сущностей должны отражаться в URL
Если есть сущности, которые состоят из других сущностей, то нужно показать это в адресе ресурса. Это поможет понять структуру и связи между сущностями.
✅ GET /v1/articles/{id}/comments
❌ GET /v1/article-comments?article_id={id}

Используем подходящие коды ошибок
Существует много кодов HTTP. Важно, чтобы HTTP-код был верным
✅ возвращать код 200, когда всё ОК и запрос отработал без ошибок
✅ “пятисотить” только в случае аварийной ситуации/багов/исключений на нашей стороне
✅ по коду HTTP понятно состояние запроса, например, 404 – не найдено
❌ возвращать код 200 с информацией об ошибке в body
❌ возвращать код 5xx, когда получена стандартная ошибка
❌ всегда возвращать коды 400 или 500 без использования разнообразия

Используем уместные HTTP-методы
GET – получение данных о ресурсах
POST – создание новых ресурсов
PUT – полное обновление существующих ресурсов
PATCH – обновление только определённых полей уже существующих ресурсов
DELETE – удаление ресурса

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

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

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

Например, есть метод публикации статьи, который уже на проде и используется несколькими потребителями. Необходимо добавить новый обязательный параметр в теле входящего запроса:
✅ Создать новую версию API метода POST /v2/articles и добавить новый параметр туда, а POST /v1/articles оставить без изменений
❌ Выкатить изменения сразу на POST /articles без всякого версионирования, чтобы потребителям жилось веселее

Ещё несколько рекомендаций

❌ Передавать токены аутентификации в URL или в body
✅ Передавать токены аутентификации в заголовках

✅ Использовать kebab-case для URL и camelCase для параметров

✅ Использовать даты в формате ISO 8601. Отображение дат в конкретном часовом поясе – задача клиента.

✅ Возвращать созданные ресурсы после POST. Это поможет клиенту, например, узнать сгенерированный ID и не делать лишних запросов

✅ Используйте PUT, если нужно заменить ресурс целиком. Используйте PATCH, если нужно изменить в ресурсе лишь часть данных.

📎 Статьи
1. Наилучшие практики создания REST API — Habr
2. RESTful web API design — Microsoft
3. Как проектировать веб-API: 7 самых важных вопросов — Babok School
4. Best Practices, которые стоит использовать при проектировании REST API⁠⁠ — советы от ведущего системного аналитика
5. Как построить REST-like API в крупном проекте — опыт от ЮMoney
6. Рекомендации по REST API — примеры Habr

⏯ Видео
1. Проектирование API в терминах RESTful — доклад Алексея Романова на конференции Analyst Days EA #1
2. Паттерны проектирования API — доклад Андрея Буракова из VK Pay на конференции Analyst Days-12 (скачать .pptx)
3. Как аналитику спроектировать свой REST API — демо-занятие курса от OTUS

📚 Книги
1. Джей Гивакс. Паттерны проектирования API
2. Арно Лоре. Проектирование веб-API
3. Сергей Константинов. API

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

GraphQL: основные понятия

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

Главная фишка GraphQL: клиент может получить все нужные данные одним запросом к одному эндпоинту, даже если они будут располагаться в разных источниках. При этом структуру ответа определяет сам потребитель.

⚙️ Принцип работы

По сути GraphQL выполняет роль оркестратора – переадресовывает фрагменты запроса на разные сервисы. GraphQL умеет отправлять данные поверх HTTP-протокола, Websocket и SSH.

В GraphQL есть всего два вида запросов:
1. query – запросы на чтение данных (используется метод GET в HTTP)
2. mutation – запросы на изменение данных (используется метод POST в HTTP)

То есть, если рассматривать акроним CRUD, то query – это R, а mutation – это RUD.

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

GraphQL имеет строгую типизацию. Типы бывают следующие:

▪️Объектные – сущности с вложенными полями и другими сущностями
▪️Скалярные – могут содержать только одно атомарное значение. К ним относятся:
▫️ Int (целочисленные) — 32-битное целое число со знаком;
▫️ Float — число двойной точности с плавающей точкой со знаком;
▫️ String — строка, закодированная в UTF-8;
▫️ Boolean (булевы) — логический тип (true или false).

Пример запроса GraphQL

query {
  user(id: 123) {
    name
    email
    age
  }
}

Пример ответа

{
  "data": {
    "user": {
      "name": "John Doe",
      "email": "johndoe@example.com",
      "age": 30
    }
  }
}

🚧 Ограничения

➖ Сложность. Для небольших простых приложений настройка таких запросов может показаться слишком сложной и ненужной. В этой ситуации легко можно обойтись классическим REST-подходом

➖ Нет кеширования. GraphQL использует всего одну конечную точку, что не позволяет следовать спецификации HTTP-кеширования. Это очень важно, так как кеширование уменьшает объем трафика.

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

➖ Трудности обеспечения безопасности с учётом всех возможных вариантов запросов

💻 Применение GraphQL

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

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

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

🌐 Официальная документация

📑 Статьи (теория)
1. Что такое GraphQL — статья от ListenIT + видео-версия
2. Подробности о GraphQL: что, как и почему — статья от RUVDS
3. The complete GraphQL Security Guide — про безопасность на EN
4. Начало работы с безопасностью GraphQL — про безопасность на RU

📝 Статьи (практика)
1. Проектируем GraphQL API в микросервисной архитектуре — опыт от Звука
2. Как и для чего мы два раза переезжали на GraphQL — опыт Яндекс.Афиши
3. GraphQL: от восторга до разочарования
4. Что не так с GraphQL — взгляд разработчика
5. Знакомство с GraphQL: примеры запросов к своей БД в облаке Hasura — туториал для аналитиков, если хотите потыкать ручками

⏯ Видео и вебинары
1. GraphQL — проектируем интеграцию систем — Анна Овзяк
2. А нужен ли нам GraphQL? — Павел Черторогов
3. Все о GraphQL за 30 минут — от разработчика
4. Про безопасность GraphQL

👐 Открытое API GraphQL
1. API GitHub — документация + попробовать онлайн
2. API Space X онлайн

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

🆚 GraphQL vs REST: сравнение по пунктам

И снова рубрика #сравнение.
Ранее мы писали главное о GraphQL и собрали материалы для изучения, а сегодня попробуем понять, может ли он заменить REST.

Все запросы идут через один эндпоинт

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

🔸 В GraphQL клиенты могут получать данные из нескольких сервисов одним запросом к одной конечной точке.

Получаем только то, что нам нужно

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

🔸 В GraphQL клиент может именно те данные, которые им нужны, указывая в запросах необходимые поля. Это позволяет избежать избыточной или недостаточной выборки данных, сокращая объем ненужной информации, передаваемой между клиентом и сервером.

Схема данных и типизация

🔹 Классический REST не даёт строгих определений по используемым типам и не определяет схему данных. Однако можно использовать, например, спецификацию OpenAPI.

🔸 GraphQL требует определения схемы, которая описывает все данные и их типы, а также способы доступа клиентов к этим данным или их изменения.

Сложнее версионирование API

🔹 В REST мы легко можем внедрить новую версию метода, не прекращая поддержку старой. Например, если для метода получения статей в блоге нужно добавить новый обязательный параметр в теле входящего запроса, то мы можем создать новую версию API метода POST /v2/articles и добавить новый параметр туда, а POST /v1/articles оставить без изменений. Таким образом, будет соблюдено требование обратной совместимости: потребители смогут пользоваться старой версией пока не перейдут на новую самостоятельно.

🔸 GraphQL не поддерживает версионирование по URL, так как у нас только одна точка входа. Однако версионирование можно организовать через создание новых query либо настроить специальные предупреждения для устаревших полей, возвращаемых клиенту.

Сложность кэширования запросов

🔹 Кэширование – это один из 6 принципов REST. В REST мы можем кэшировать запросы к эндпоинтам. Это позволяет снизить нагрузку на серверы и ускоряет получение ответа для клиента.

🔸 Хотя физически в GraphQL можно реализовать кэширование на уровне запросов, в реальности этим не занимаются, так как вариаций запросов может существовать бесчисленное множество. В одном запросе вы можете затребовать имя автора, а в следующем – не только имя автора, но и адрес его электронной почты. Именно для таких случаев вам понадобится более филигранный кэш на уровне полей, а реализовать его не так-то просто. Однако, большинство библиотек, построенных поверх GraphQL, предлагают такие механизмы кэширования прямо «из коробки».

Нет кодов состояний

🔹 REST позволяет возвращать любые доступные коды ответов HTTP, что позволяет клиенту понять результат запроса и среагировать на него.

🔸 GraphQL обычно возвращает статус 200 OK даже с ошибкой, но при использовании специальных клиентов эта проблема легко решается.


❓Что использовать в работе

Итак, REST API применяют, если:
➖ работают с небольшими программами, где нужно обрабатывать простые данные
➖ пользователи работают с ними одинаково
➖ нет требований к сложным запросам

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

📎 Ссылки
1. REST API vs GraphQL: в чём между ними разница — МТС
2. В чем разница между GraphQL и REST? — Amazon
3. Сравнение REST и GraphQL
4. GraphQL vs REST: 4 Critical Differences
5. GraphQL vs REST - кто круче? — видео

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

И как всегда для удобства сравнение GraphQL vs REST картинкой

📣 делитесь с коллегами

#сравнение

🚀 Большая подборка открытых API

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

📣 Сохраняйте себе и пересылайте коллегам!

REST API
1. Swagger Petstore — официальный тренажёр от Сваггера
2. Space X API — коллекция Postman (можно и онлайн)
3. VK API — можно онлайн
4. REST API для GitHub + коллекция Postman
5. API ФИАС (КЛАДР)
6. Тренажёр REST Ninja + Swagger-документация
7. API DaData
8. Polygon.io Stocks API — агрегатор API с фондовых бирж США. Есть библиотеки для Python, Go, Javanoscript, PHP, Kotlin
9. Blockchain.com Exchange REST API — сваггер популярной биржи криптовалют
10. Kraken REST API — пример подробной документации API и спецификации в формате OpenAPI + примеры кода на Python
➕ Ещё примеры открытых REST API

GraphQL
1. API GitHub — документация + попробовать онлайн
2. API Space X онлайн
3. Shopify GraphQL API
4. Открытое API с данными о странах + документация и исходники
5. API с данными о товарах Amazon + документация + репозиторий
6. API сайта любителей аниме-манг + документация
➕ Ещё примеры открытых GraphQL API

SOAP
1. Центробанк России
2. Сервис конвертации чисел — онлайн + Postman-коллекция
3. SOAP-песочница
4. PayPal SOAP API

JSON-RPC
1. Обёртка для Solana JSON-RPC, официальная документация
2. Пример OpenRPC + документация
3. Пример документации для JSON-RPC API
4. JSON-RPC API для zkLink

gRPC
1. Google API
2. Google Cloud Bigtable gRPC API

Websockets
1. Binance WebSocket API Documentation — API криптобиржи
2. Gate.io Spot WebSocket v4 — ещё пример от биржи криптовалют, есть примеры кода на Python
3. Polygon.io WebSocket API — агрегатор API с фондовых бирж США. Есть библиотеки для Python, Go, Javanoscript, PHP, Kotlin
4. Blockchain.com Websocket API — документация от популярной биржи криптовалют с примерами кода на Python
5. EXMO Websocket API + пример документации API в Postman (Websockets и REST)

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

JSON-RPC: что это такое и чем отличается от REST

JSON-RPC – это простой протокол для создания API в стиле RPC (Remote Procedure Call).

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

Все запросы отправляются только в один эндпоинт. Для отправки запросов в качестве транспорта может использоваться что угодно, но как правило, используется протокол HTTP, а точнее, лишь только один его метод – POST.

Как вы поняли из названия, все сообщения представляются в формате JSON. В отличие от REST, JSON-RPC вводит требования к составу запросов и ответов – они должны включать обязательные элементы.

➡️ Запросы могут содержать следующие свойства:
1. jsonrpc — версия JSON-RPC (актуальная 2.0)
2. method – строка с именем вызываемого метода
3. params – массив данных, передаваемых на сервер
4. id – значение любого типа, которое используется для установки соответствия между запросом и ответом.

⬅️ Ответы сервера должны содержать следующие элементы:
1. jsonrpc — версия JSON-RPC (актуальная 2.0)
2. result – данные в случае успеха; error — код ошибки, если произошла ошибка
3. id – то же значение, что и в запросе, к которому относится данный ответ

Примеры запросов и ответов

Запрос

{"jsonrpc": "2.0", "method": "post.like", "params": {"post": "12345"}, "id": 1}

Успешный ответ

{"jsonrpc": "2.0", "result": {"likes": 123}, "id": 1}

Ответ с ошибкой

{"jsonrpc": "2.0", "error": {"code": 666, "message": "Post not found"}, "id": "1"}

Таким образом, JSON-RPC более формализован, чем REST. Потенциально это может уменьшить количество разногласий и разночтений в команде, однако обратная сторона формализации – снижение гибкости.

✅ Ещё пара фишек JSON-RPC
1. Запросы можно группировать в пакеты, подобно gRPC.
2. Можно отправлять запросы-уведомления, не требующие ответа от сервера (в таком случае не передаётся id в запросе).

🚧 Ограничения JSON-RPC

➖ Сложность кэширования. RPC не поддерживает использование инфраструктурного кэширования (например, CDN), так как использует только метод POST, который не является идемпотентным, то есть многократное повторение одних и тех же запросов POST может возвращать разные результаты.

➖ Сложность балансировки нагрузки. Балансировка нагрузки в JSON-RPC не так проста и эффективна, как в REST, который предлагает разные HTTP-методы, коды ответов и заголовки для управления балансировкой нагрузки
В случае возникновения ошибок на одной из нод, JSON-RPC не может перенаправить запрос на другую ноду, в отличие от REST, который использует коды ответов HTTP и заголовки для управления балансировкой нагрузки.

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

➖ Нет поддержки кодов состояний HTTP.

Когда лучше использовать JSON-RPC вместо REST

Как обычно: нет лучшего рецепта и всё зависит от ситуации.
JSON-RPC может оказаться эффективнее, когда:

1️⃣ Требуются сложные вычисления (HTTP-глаголов недостаточно), затрагивающие множество действий и объектов.

2️⃣ Предметная область специфична и не поддаётся адекватному разбиению на ресурсы, а всё взаимодействие заключается в запуске удалённых процедур.

3️⃣ Требуется работать над другими каналами передачи данных, кроме HTTP, или поддерживать открытое соединение (например, через WebSockets).

📎 Материалы
1. REST? Возьмите тупой JSON-RPC
2. Статьи от разработчика-адепта JSON-RPC: часть 1, часть 2
3. JSON-RPC? Возьмите хитрый REST — критика JSON-RPC
4. Обзорная статья от Merion Academy
5. Видео JSON-RPC или когда REST неудобен

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

JSON-RPC vs REST картинкой

📣 делитесь с коллегами

#сравнение

Impact Mapping. Как повысить эффективность программных продуктов и проектов по их разработке

✍️ Автор: Гойко Аджич
📅 Год: 2017
🔤 Язык: русский

Эта книга — практическое пособие по impact mapping (картам влияния), простому, но очень эффективному методу разработки программного обеспечения. Он помогает еще на стадии стратегического планирования организовать сотрудничество различных специалистов и в результате создавать эффективные программные продукты.
Почему книга достойна прочтения:
— Impact maps позволяют составлять планы, которые обеспечат соответствие разрабатываемого программного обеспечения бизнес-целям организации.
— Они также помогают легко адаптировать программное обеспечение в ходе работы над проектом.
— Этот инструмент универсален и подойдет как для Agile-проектов, так и для классического проектного подхода.

Обзор книги на vc.ru

#планирование #стратегия

🛡Безопасность API: базовые принципы

Проектирование API не ограничивается реализацией HTTP запросов в определенном стиле и формированием ответов в соответствии со спецификацией. Крайне важно уделить внимание вопросам безопасности.

Способы обеспечения безопасности

1️⃣ Использование зашифрованного протокола TLS. Рекомендуется шифровать трафик запросов и ответов API для защиты конфиденциальности информации при передаче по незащищенным сетям. Общепринятой практикой является использование протокола шифрования TLS. Поверх TLS работает HTTPS, о котором мы уже писали.

2️⃣ Авторизация запросов. Авторизация подразумевает, что данному клиенту разрешено выполнять операцию над ресурсом. Следует учитывать:
▪️Проверку прав доступа к объектам при каждом запросе.
▪️Проверку того, что залогиненный пользователь имеет доступ только к разрешенным объектам.
▪️ID объектов должны быть сложными для подбора, например в виде UUID, а не простая последовательность 1, 2, 3.

3️⃣ Проверка содержимого запроса. Необходимо проверять, что запрос не содержит опасных компонентов (например, SQL-инъекции, XSS-атаки, DTD-атаки). При этом недопустимо автоматически десериализовать пришедшие данные и записывать их в БД без каких-либо проверок бизнес-логики и прав доступа.

4️⃣ Проверка скорости и количества запросов: контроль, что запросы API не превышают определенной скорости для защиты сервиса от перегрузки или атак. Может настраивать квоты запросов на клиента. Сюда входит, например, блокировка IP по результатам неудачных попыток входа.

5️⃣ Контроль размера запроса: проверяет, что полезная нагрузка запроса не превышает ограничения для операции API. Предотвращает попадание неправильных (больших) запросов к сервису.

6️⃣ Мониторинг безопасности: логировние ключевых событий, таких как неудачные попытки аутентификации, отказы в доступе, ошибки валидации входных данных. Также следует мониторить инфраструктуру, сетевую активность, загрузку ОС. Важно настроить алерты, чтобы максимально оперативно реагировать на риски.

7️⃣ Если API непубличное, следует ограничить адреса, с которых разрешено использование API. Также можно ограничивать HTTP методы, которые могут быть использованы для доступа к API и задать список заголовков, которые сервер может принимать.

📄 Стандарты в области безопасности API
1. OWASP (Open Web Application Security Project), а также есть стьтья-перевод на русском на Хабре
2. RFC 7519 — JSON Web Token (JWT)
3. OAuth 2.0, простым языком: статья на Хабре

📑 Статьи
1. Безопасность REST API от А до ПИ
2. Рекомендации по проектированию безопасности API для внутренних и облачных систем
3. Требования аутентификации и авторизации API — раздел открытого курса по документированию API
4. Защита API от атак — статья на Tadviser от ИБ-компании
5. Требования к информационной безопасности: кого вовлекать в выявление? — статья Алексея Краснова на Systems.Education

⏯ Видео
1. Защита API и микросервисной инфраструктуры — доклад директора ИБ-компании
2. Тестирование безопасности API — Катерина Овеченко. QA Fest 2019
3. Курс видеолекций "Безопасность интернет-приложений" от Mail.ru Group, МГТУ им. Н.Э. Баумана (осень 2014)
4. Основы безопасности веб-приложений — вебинар от Skillbox
5. Открытая лекция Академии Яндекса про безопасность веб-приложений (2017)
6. Информационная безопасность в аналитике — доклад Галины Матвеевой на конференции Analyst Days-9
7. Информационная безопасность и криптография. Точка зрения аналитика — доклад Сергея Евтуховича на конференции Analyst Days #15

Инфографика по безопасности API

#безопасность #api