📐 GraphQL API
Запрос:
⌨️ graphql
{
taxpayer(inn: "1234567890") {
inn
name
registered
status
}
}

Ответ:
⌨️json
{
"data": {
"taxpayer": {
"inn": "1234567890",
"name": "Иванов Иван Иванович",
"registered": "2020-01-01",
"status": "active"
}
}
}

-----------------------------

📐 gRPC
Для gRPC сначала требуется описание протокола в .proto файле:
⌨️ protobuf

syntax = "proto3";

package taxservice;

service TaxService {
rpc GetTaxpayerInfo (TaxpayerRequest) returns (TaxpayerInfo);
}

message TaxpayerRequest {
string inn = 1;
}

message TaxpayerInfo {
string inn = 1;
string name = 2;
string registered = 3;
string status = 4;
}

Запрос (клиентский код на Python, например):
⌨️python
import grpc
import taxservice_pb2
import taxservice_pb2_grpc

channel = grpc.insecure_channel('api.taxservice.com:50051')
stub = taxservice_pb2_grpc.TaxServiceStub(channel)
response = stub.GetTaxpayerInfo(taxservice_pb2.TaxpayerRequest(inn="1234567890"))
print(response)

Ответ (представлен в виде объекта):
⌨️python
inn: "1234567890"
name: "Иванов Иван Иванович"
registered: "2020-01-01"
status: "active"
-----------------------------
👇👇👇

📐WebSocket API
WebSocket, как правило, используется для двустороннего взаимодействия, поэтому здесь будет инициировано соединение, затем отправлен запрос, и в ответ придет нужная информация.

Запрос (пример на JavaScript):
⌨️ javascript
let socket = new WebSocket("wss://api.taxservice.com/taxpayers");

socket.onopen = function(event) {
let requestData = {
action: "getTaxpayerInfo",
inn: "1234567890"
};
socket.send(JSON.stringify(requestData));
};

socket.onmessage = function(event) {
let responseData = JSON.parse(event.data);
console.log(responseData);
};

Ответ (полученный от сервера):
⌨️ json
{
"action": "taxpayerInfo",
"data": {
"inn": "1234567890",
"name": "Иванов Иван Иванович",
"registered": "2020-01-01",
"status": "active"
}
}

-----------------------------

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

‼️ Важны примеры-образцы: открытые протоколы API ‼️

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

🔹REST API
Spotify: Музыкальная стриминговая платформа Spotify предоставляет RESTful API, который позволяет разработчикам создавать приложения, которые взаимодействуют с каталогом Spotify, плейлистами, артистами и многим другим.
Spotify Web API

🔹SOAP API
PayPal: Для некоторых из своих сервисов PayPal предоставляет SOAP API, позволяя интегрировать возможности оплаты и управления транзакциями.
PayPal SOAP API
Пример метода получения баланса для удобства.

🔹GraphQL API
Shopify: Shopify использует GraphQL для предоставления гибкого и эффективного способа взаимодействия с их платформой электронной коммерции.
Shopify GraphQL API

🔹gRPC
Google Cloud: Многие сервисы Google Cloud Platform предоставляют gRPC API. Например, сервис Bigtable от Google имеет такой интерфейс.
Google Cloud Bigtable gRPC API

🔹WebSocket API
Binance: Биржа криптовалют Binance предоставляет WebSocket API для мгновенного получения информации о торговле.
Binance WebSocket API Documentation


Сохраняйте в избранное на будущее, чтобы иметь примеры всех видов API документации под рукой, и делитесь с коллегами аналитиками, кто интересовался темой API 🤝

Погружаемся в REST API 😎

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

Его главная цель - облегчить передачу информации между разными системами и управлять ей: создавать, читать, изменять, удалять. REST API использует для этого стандартные HTTP-запросы: GET, POST, PUT, DELETE и другие.

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

Еще пример: у национального аэрокосмического управления США (NASA) есть REST API, который предоставляет доступ к различной информации о космических миссиях, астрономических событиях и многом другом.
Ссылка на документацию API NASA 🔗

Отличие REST API от других видов API, таких как SOAP API, ftp и RPC, заключается в том, что REST API не имеет жестких правил и структур, и может быть использован с любым языком программирования - java, Python, C++ и другие.

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

REST API - это набор правил проектирования пограммных интерфейсов (API), введенный Роем Филдингом, одним из основных авторов спецификации HTTP: Ссылка на основополагающий документ.

Что еще вам интересно узнать про REST API? Пишите в комментарии 📝

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

Вот несколько ситуаций, в которых использование REST API может оказаться неверным решением:

❌ Непрерывное Взаимодействие в Реальном Времени:
Для приложений, требующих постоянного соединения для быстрого обмена данными в реальном времени (например, онлайн-игры, чаты), WebSocket или другие протоколы реального времени могут быть более подходящими.

❌ Клиенты требуют различных наборов данных: Если клиенты (например, мобильное приложение и веб-сайт) требуют разных наборов данных, GraphQL может предоставить больше гибкости, позволяя клиентам запрашивать только те данные, которые им нужны.

❌ Бинарный Протокол: Если требуется эффективность и минимальные затраты на передачу данных, то протоколы, такие как gRPC, которые используют бинарные форматы передачи данных, могут быть более эффективными.

❌ Служебная Информация: Если ваш API должен передавать много служебной информации вместе с данными (например, метаданными или инструкциями обработки), SOAP может быть более подходящим, так как он предоставляет стандартизированный способ включения такой информации в сообщения.

❌ Обратная Совместимость: Если ваша система уже имеет существующие интеграции на основе другого протокола (например, SOAP), и переход на REST может вызвать сбои или требует значительной переработки, может быть рационально продолжить использовать текущий протокол.

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

Зачем проектировать REST API? 🧐

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

🤝 Результатом проектирования REST API является его дизайн. Дизайн REST API - это контракт между разработчиками Backend и Frontend.

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

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


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

Оффер на 300 💵

По данным сайта hh.ru, средняя зарплата системного аналитика с навыками проектирования REST API в Москве варьируется от 250 000 до 350 000 рублей в месяц, а максимальная может достигать 440 000 рублей в месяц и выше, в зависимости от опыта работы и квалификации.


🔑 Вакансии из актуального:
Ведущий системный аналитик от 360 000 до 440 000 ₽ на руки:
https://hh.ru/vacancy/87942503
Системный аналитик от 250 000 до 350 000 ₽ на руки:
https://hh.ru/vacancy/87724926
https://hh.ru/vacancy/86763585
https://hh.ru/vacancy/87025113

Связанные навыки:
🔑 Взаимодействие с разработчиками и техническими архитекторами.
🔑 Опыт работы с интеграциями SOAP, REST, очереди.
🔑 Понимание REST/SOAP.
🔑 Умение проверить api посредством Postman.
🔑 Практический опыт работы и проектирования REST API.
🔑 Практический опыт работы с мобильными приложениями.
🔑 Практической опыт декомпозиции и проектирования сервисов.


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

Что еще важно, этим навыком хорошо владеют не все разработчики. Поэтому очень часто руководители проектов ищут куда направить своих коллег, чтобы они глубоко разбирались в REST API и знали best-practice в его проектировании 🙌

🤖 Разработка REST API зона ответственности Backend-команды (сервер-приложение).

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

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

Системный аналитик может внести следующий вклад в реализацию задачи по проектированию REST API:

🟢 предоставить информацию о том, какие данные нужны для взаимодействия систем, и как эти данные должны быть организованы;

🟢 предложить использовать соответствующие действиям в системе HTTP-метод, такие как GET, POST, PUT и DELETE;

🟢 предложить использовать определенные структуры JSON-объектов для передачи данных в API;

🟢 помочь обеспечить безопасность API, выбрав механизм аутентификации и авторизации;

🟢 документировать API в Confluence, Postman или Swagger для облегчения взаимодействия между системными аналитиками, тим-лидами и разработчиками;

🟢 тестировать API через Postman, для проверки правильности его работы и соответствия постановке задачи.


P.S. Посмотрите классный пример API-документации в Postman от Twitter ❤️

Я, как системный аналитик, всегда очень хорошо знают весь проект с которым работаю: и видимый пользовательский интерфейс (UI), и скрытый за строками кода программный интерфейс (API).

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

Утренний кофе оказался на белой рубашке. Крышечка солонки открылась, пока солил суп. Пробка на дороге затянулась намного дольше, чем ожидалось. Жизнь полна неожиданностей, и иногда мы чувствуем, что потеряли контроль.
Самосовершенствование — это не только о больших целях и амбициях. Это также о том, как преодолевать мелкие трудности и становиться лучше каждый день. 🌱

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

🤔 Не понимаешь, нужно ли это вообще? В каждом маленьком достижении скрыто огромное значение. Оно делает нас увереннее в себе и открывает двери к большим изменениям.
Совет: Устанавливай небольшие, конкретные цели для себя каждую неделю. Это может быть что-то вроде: "Научиться готовить новое блюдо" или "Прочитать 50 страниц книги". Цель должна быть измеримой, чтобы ты мог почувствовать удовлетворение от её достижения.

Для меня когда-то английский язык был непостижим, а пробежать 30 мин вызывало приступы паники. Сегодня я рассказываю шутки на английском и бегаю по 40 мин со скоростью 11км/час на дорожке в зале или по улице. И мне в кайф, что я могу, хотя когда-то это было нереально!

Самосовершенствование начинается прямо здесь и сейчас, с мелочей повседневной жизни. И пусть мир вокруг будет полон неожиданностей и испытаний, ты всегда можешь стать лучше, используя простые, доступные инструменты.
Какими недавними примерами самосовершенствования из вашей жизни вы можете поделиться? Что получалось, а что нет? Пишите в комментариях! 🌺👇🏼

🚀 Всё о REST API за 1 минуту! 🚀


1️⃣ Ресурсы (Resources):
Всё в REST – это ресурсы. Они идентифицируются через URL (напр. `/users`).
Ресурс — это всё, что вы хотите показать внешнему миру через ваше приложение.

2️⃣ Методы - основные:
- GET: читать
- POST: создавать
- PUT: обновлять полностью
- PATCH: частично обновлять
- DELETE: удалять

3️⃣ Состояние:
REST — "без сохранения состояния" (stateless). Каждый новый запрос не зависит от других,.

4️⃣ Форматы сообщений:
JSON и XML — самые популярные форматы для передачи данных в Body (теле запроса). Но не единственные.

5️⃣ Коды ответов:
- 200: ОК
- 201: Создано (идеально для успешных POST, PUT)
- 400: Неверный запрос
- 401: Не авторизован
- 404: Не найдено
... и многие другие.

6️⃣ CRUD: Create, Read, Update, Delete — основные операции.

7️⃣ Безопасность: Важно обеспечивать безопасность при передаче данных — HTTPS, аутентификация и авторизация.

И картинка! Я, пожалуй, тоже сохраню этот пост! ❤️ #RESTAPI_getanalyst

‼️ 5 важных принципов дизайна REST API, которые помогут сделать его понятным и удобным для использования ‼️

Разбираем на примере объекта "счет" для банквской системы.

1️⃣ HTTP-методы = действия, не дублируйте в названиях эндпоинтов (методов):
• GET /account - просмотр списка счетов,
• POST /account - открытие нового счета,
• DELETE /account/77 - закрытие счета с номером 77.
Не рекомендуется делать POST /createAccount, за действие create уже отвечает POST. А то получится "масло маслянное". Хотя иногда бывают исключения, куда же без них.

2️⃣ Создавайте читаемые URL, в едином стиле:
• GET .../account - счета, список (от англ. "счет"),
• GET .../account/123 - информация по счету 123,
• GET .../account/123/transaction - история операций по счету 123.
Обратите внимание, что все объекты данных в ед. числе (допустимо во множественном). Выстраивается логическая иерархия по доступам к объектам.

3️⃣ Версионируйте API - добавляйте версию в URL:
• GET .../api/v1/account - первая версия API,
• GET .../api/v2/account - вторая версия.
Это необходимо для поддержания обратной совместимости при проектировании API, если в процессе доработки изменена иерархия объектов в JSON, изменены типы данных и другие несовместимые доработки.

4️⃣ Возвращайте верные коды ответа, в соответствии со стандартом HTTP:
• 200 - всё ок,
• 400 - ошибка запроса,
• 404 - данные не найдены.
• 418 - я — чайник.
Это поможет клиентам API понять, что произошло, и принять соответствующие действия. Это аналитики прописывают в требованиях к ответам на запросы.

5️⃣ Используйте формат данных, понятный клиенту REST API. Обычно это JSON или XML. Его задают в Headers запроса:
• application/json - для JSON,
• application/xml - для XML.
Это позволяет клиентам легко интерпретировать ответы от сервера. Можно дополнять ответы внутренним кодом, сообщением и другой информацией.


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

🤔Каково быть системным аналитиком?
Мир IT всегда был для меня местом, где встречаются технологии, искусство и бизнес. И именно в роли системного аналитика я однажды нашла свое место.

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

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

В роли системного аналитика я не просто пишу требования к системам. Я помогаю создавать и развивать бизнес за счет автоматизации.

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

🌟 А возможность работы из любой точки мира - это отдельная часть удовольствия от рабочих процессов!

🌱 Я убеждена, что в мире IT нет предела совершенству. Каждый новый проект, каждая задача – это шанс стать лучшей версией себя.

Я выбрала не просто профессию системного аналитика. Я выбрала путь постоянного самосовершенствования, открытий и радости от результатов 🙌

📋 Задачи системного аналитика при проектировании REST API:

1. Сделать описание метод - что это и для чего.
2. Описать логику его работы - алгоритм.
3. Определить формат запросов и ответов, влияние на БД.

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

⬇️⬇️⬇️⬇️⬇️

🔵 Функциональные требования к проекту TMS

Управление задачами:
▫️Создание новой задачи: Пользователь должен иметь возможность создать новую задачу, указав её описание, приоритет, срок исполнения и другие необходимые параметры.
▫️Создание комментария к задаче: Пользователь может добавить комментарий к определенной задаче, описывая ход выполнения, проблемы или другие замечания.
▫️Изменение статуса задачи: Пользователь может менять статус задачи (например, "в работе", "завершено", "отложено").
▫️Изменение приоритета задачи: Пользователь может изменить приоритет задачи в зависимости от её актуальности.

Взаимодействие с пользователями:
▫️Получение списка всех задач: Пользователи могут просматривать общий список задач, чтобы понимать общий объем работы.
▫️Получение списка задач определённого пользователя: Любой пользователь может просмотреть список задач, назначенных конкретному коллеге.
▫️Получение деталей конкретной задачи: Пользователь должен иметь возможность увидеть все детали задачи, включая её статус, исполнителя и историю изменений.
▫️Получение деталей конкретного пользователя: Позволяет узнать общую информацию о пользователе, а также его активные и завершенные задачи.

Стоит отметить, что функциональность Task Management System (TMS) может быть гораздо шире, и это лишь малая часть методов, которые могут быть реализованы в реальной системе.

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

📌POST в REST API

Один из основных HTTP-методов, используемых в REST - это POST.

HTTP-метод POST в контексте REST API обычно используется для создания новой записи в БД. Это может быть, например, новый товар в интернет-магазине, новый комментарий на веб-сайте или новый пользователь при регистрации в системе.


Когда используется POST?

🟢 Необходимо добавить новую запись, создать данные в БД.
🟢 Сервер должен сгенерировать уникальный идентификатор (ID) этой новой записи.


Когда НЕ рекомендуется использовать POST?

❌Для чтения данных:
POST не должен использоваться, если вы просто хотите извлечь данные, не внося при этом изменений. Для этого лучше использовать метод GET.

❌Для обновления существующих ресурсов:
Если вы хотите изменить уже существующий ресурс, лучше использовать метод PUT (если заменяете ресурс полностью) или PATCH (если частично обновляете данные ресурса).

❌Для удаления ресурсов (данных из БД):
Для этой цели существует специальный метод DELETE.

❌Когда идемпотентность важна:
POST не является идемпотентным методом, что означает, что повторное выполнение одного и того же запроса POST может привести к различным результатам. Если вам важно, чтобы операция могла быть безопасно повторена многократно, рассмотрите использование идемпотентного метода PUT.

Основные рекомендации при выборе POST:


🌟 Метод POST создает одну или несколько записей в БД, в зависимости от переданного тела запроса (JSON/XML/...) - один объект или массив (список объектов).

POST https://tms.com/api/v1/tasks или POST https://tms.com/api/v1/task - создать задачу.
POST https://tms.com/api/v1/user - зарегистрировать пользователя.
POST https://tms.com/api/v1/user/{userId}/task - создать задачу для пользователя с идентификатором {userId}*.



🌟 Метод POST используется, когда id записи при ее создании в БД генерируется на сервере.

POST https://tms.com/api/v1/task/{taskId} - создать задачу и присвоить ей id в БД со значением {taskId}*. Не рекомендуется так делать, т.к. id генерируется на клиенте. Лучше PUT, а не POST.

*{userId} и {taskId} - указатели на конкретные объекты данных в БД по их уникальным id.
Пример для id задачи = 123: POST https://tms.com/api/v1/task/123.



🌟 Тело запроса POST обычно содержит данные для создания новой записи в формате JSON или XML (+ другие форматы). Но это не обязательно. Данные также могут быть переданы в query-параметрах, headers или просто не требоваться при создании записи в БД (например, при авто-генерации данных на сервере).

POST https://tms.com/api/v1/task?name=Документирование - создать задачу с названием “Документирование”, name - query-параметр. Лучше все же это отправлять в Body, т.к. название может быть длинным и влиять на длину URL.




🌟 При успешном выполнении POST-запроса возвращается статус 201 (Created) с информацией о созданной записи. Информацию о созданной записи возвращать не обязательно. Можно вернуть пустое тело ответа.


Эти детали стоит помнить и проверять себя каждый раз при проектировании API 💻