📌 Примеры API популярных сервисов 📌


🔗 Облачное хранение данных (Google Drive API):

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

Проще говоря, используя Google Drive API вы можете разработать свое приложение копию Google Drive.

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


🔗 Видео-сервис (YouTube API):

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

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

Вы можете создать свое собственное приложение, которое будет воспроизводить видео с YouTube и повторять его функции, или встроить YouTube и его функции в уже работающее приложение.

Продолжение 👇

📌 Примеры API популярных сервисов 📌

🔗 Электронная коммерция (Wildberries API):

Wildberries API предоставляет продавцам инструменты для управления их магазином на платформе Wildberries. Он позволяет получать оперативную и статистическую информацию о продажах, товарах и заказах посредством HTTP RestAPI.

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

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



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

Взаимодействие систем в этом случае правильно называть - интеграция по API.

🌟 Виды API про которые нужно знать Системному аналитику 🌟

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

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


🌟 REST API (Representational State Transfer API):
Это архитектурный стиль, который определяет, по каким правилам приложения должны обмениваться данными между собой. Он используется для создания веб-сервисов, мобильных приложений, интеграционных платформ и других IT-решений.


REST API использует стандартные HTTP-методы (GET, POST, PUT, DELETE) для выполнения операций с ресурсами (объектами данных).

Объекты данных представлены в формате JSON, XML или других текстовых форматах.

Пример REST API-документации по платежам от Тинькофф.



🌟 SOAP API (Simple Object Access Protocol API):
Это протокол, который обеспечивает обмен структурированными сообщениями через Интернет.

SOAP API использует XML для представления данных и WSDL (Web Services Description Language) для описания интерфейса веб-сервиса.

Пример документации SOAP API, собранной в Postman.

👇👇👇

🌟 GraphQL API:
Это язык запросов для API, который позволяет клиентам запросить только те данные, которые им нужны, и получать эти данные в оптимизированном формате.

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

GraphQL API использует собственный язык запросов и может возвращать данные в формате JSON.

Пример интересной GraphQL API коллекции запросов в Postman со SpaceX и “Рик и Морти” 🙂


🌟 gRPC:

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

Это высокопроизводительный RPC, который работает с бинарным форматом сериализации Protocol Buffers и использует HTTP/2 для максимальной производительности.

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

Пример gRPC API документации системы DAML - общее описание и методы.


🌟 WebSocket API:
Это протокол для обмена сообщениями в режиме реального времени между веб-сервером и клиентским приложением.

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

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

Пример WebSocket API-документации.


Кроме того, существует еще множество других видов API, таких как XML-RPC, JSON-RPC, HAL, OData, и другие. Каждый API имеет свои особенности, и выбор того, какой API использовать, зависит от конкретной задачи и требований к проекту.

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


Сохраняйте пост в избранное, чтобы не потерять!

⚡️ От Junior до Senior системного аналитика, или “Как понять кто я сейчас, чтобы указать в резюме и искать работу?” ⚡️

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

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

Для справки:
🔗 Профстандарт: 06.022: Системный аналитик
🔗 STAFF and SENIOR INFORMATION SYSTEMS ANALYST (Обычный и старший Системные аналитики, Калифорнийский стандарт)

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

От Middle могут требовать знаний Senior специалиста на сложных банковских проектах или в крупных продуктовых компаниях как Тинькофф или Booking. А в компании, которые занимаются интеграциями и внедрением “коробочных продуктов” типа 1С или Битрикс24, могут требоваться системные аналитики Senior с требованиями как к Middle, но со специфическими знаниями продуктов 1С / Битрикс24.

Как же определить свой текущий грейд, если стандарты есть, но на практике они используются лишь частично?

🧐 Как же определить свой текущий грейд, если стандарты есть, но на практике они используются лишь частично?

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

3 главных блока, на которые смотрят HR и ваши будущие руководители в резюме:
🔸 Желаемая позиция и ЗП
🔸 Опыт работы
🔸 Навыки

👇👇👇


🔸Опыт работы

Заполняйте честно! Указывается только релевантный опыт.

Для Junior:
- Указать тот опыт, который был так или иначе связан с ИТ, а также перечислить ключевые задачи по части ИТ и достижения в компании в целом.
- Продолжительность практического опыта из обучения.

Для Middle и выше:
- Указать реальный опыт и достижения на местах работы.

Получится какое-то количество лет и/или месяцев. Но…
Грейд НЕ зависит от количества лет работы.

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

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

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

Продолжим завтра👇

🔸 Навыки: как влияют на грейд системного аналитика?

По актуальным вакансиям на 2024 и на основе Карты навыков Системного аналитика я собрала для вас средние ожидания от специалистов по рынку.

Пройдите по списку навыков и отметьте те, которые есть у вас.

[J - Junior (младший аналитик), Middle - M (рядовой специалист), S - Senior (старший аналитик)]

🟨 Требования и документация:
[JMS] Обследование процессов заказчиков, сбор и анализ требований.
[JMS] Знание стандартов написания ТЗ (таких как ГОСТ-34 и другие).
[JMS] Постановка задач разработчикам на новую функциональность.
[JMS] Знание Jira, Confluence.
[JMS] Умение декомпозировать задачи - делить на части.
[S] Способность самостоятельно разрабатывать требования к ведению документации проекта.

🟨 Технические навыки и инструменты:
[JMS] Умение выполнять SQL-запросы на отбор и группировку данных.
[MS] Умение проектировать БД, строить ER-диаграммы.
[JMS] Знание нотации BPMN для моделирования бизнес-процессов.
[JMS] Знание нотации UML (преимущественно sequence) для описания алгоритмов работы системы.
[JMS] Понимание принципов работы API. Отдельно выделяют REST API, SOAP API, gRPC или другие API.
[MS] Умение разрабатывать требования к интеграциям систем по API.
[S] Умение проектировать методы REST API, SOAP API или другие API.
[MS] Знание Postman, Swagger.
[MS] Понимание принципов сервисной и микросервисной архитектуры.
[S] Навык проектирования архитектуры.
[S] Знание нотаций C4 и других нотаций моделирования архитектуры.
[S] Знание принципов работы очередей сообщений (Rabbit, Kafka) и умение разрабатывать требования к ним.
[S] Знание Git.

🟨 Другие:
[JMS] Грамотность и умение четко формулировать мысли.
[JMS] Легкообучаемость.
[JMS] Внимание к деталям, дотошность.
[JMS] Понимание процесса разработки ПО и умение работать в команде (Scrum, Agile).
[JMS] Опыт тестирования ПО.
[S] Опыт мобильной разработки (не обязателен, но желателен).
[MS] Знание инструмента Figma или аналог, умение работать с макетами и требованиями к дизайну.
[S] Навык обучения сотрудников.
[MS] Способность полностью самостоятельно решать задачи.

Посчитайте сумму и определите свой грейд.


[JMS] - всего 14 - не менее 10 для позиции Junior
[MS] - всего 6 - не менее 4 для позиции Middle
[S] - всего 8 - не менее 5 для позиции Senior


Поздравляю! Если Вы прошли эти шаги, то Вы успешно определили свой грейд В ТЕОРИИ. А что на практике?

P.S. Хочу подсветить, что еще есть вакансии Junior+, Middle+, Middle/Middle, Lead - Ведущий аналитик, Руководитель отдела. Есть не только три базовых грейда.

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

🔸 Грейд аналитика по факту: как определить без теории и стандартов.

После того, как вы в теории поняли какой у вас грейд и отметили в списке все свои навыки в списке выше, я рекомендую:

1. Открыть сайт с вакансиями или другой ресурс (в этой статье есть рекомендации по ресурсам поиска работы СА по всему миру), и выполнить поиск по желаемому грейду или выше.

2. Открыть 5 вакансий компаний, в которых вы бы хотели работать.

3. Сопоставить их требования с вашим списком навыков, которые вы отметили выше.

4. Если соответствуете на 80% и более - отлично. Под этот грейд и ЗП и оформляем своё резюме. А если нет, то возможно стоит опуститься на грейд пониже в процессе поиска работы, хотя в резюме можно при этом оставить более высокий грейд. Но это может вызвать вопросы при откликах.

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

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

6. ЗП укажите при необходимости, ориентируясь на актуальные вилки по Вашему грейду на ресурсе, где вы искали работы. Также их можно посмотреть на сайте zarplan.



Заключение 👀

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

REST API - что это?

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

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

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

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

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

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

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

А тут точно нужно REST? 👀

REST является одним из наиболее популярных для разработки веб-сервисов.

По итогам опросов, проводимых Postman, его использование немного снизилось за последние два года — с 92% до 86%. Но его простота, масштабируемость и легкость в интеграциях с веб-сервисами закрепляют его позицию на первом месте.

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

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

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

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

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

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

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

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

👉 Что такое “Дизайн REST API” и когда возникает потребность в нём?

Дизайн REST API - это процесс анализа требований к взаимодействию систем, и проектирования форматов запросов и ответов для его реализации.

1. Определить тип HTTP-метода: GET, POST...
2. Дать название эндпоинта - URL.
3. Определить параметры, заголовки и тело JSON для запроса.
4. Определить возможные HTTP-коды, заголовки и тела JSON для ответов.

Результатом этого процесса является предварительная API-документация, которую также называют контрактом API.

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

🔺 Контракт REST API создается до написания программного кода разработчиками Backend. Зачем?

Мобильные и веб- приложения (frontend) - клиенты API, хотят с помощью API получать данные из БД сервера и показывать пользователям.
Например, данные о балансе счета и истории операций в банковском приложении.

Для Frontend-разработчиков наличие контракта API до того, как его фактически запрограммируют, помогает:

+ Начать разрабатывать свой код frontend-приложений и работать с подключением к нему API на заглушках, создаваемых на основе контракта REST API.
В это время, параллельно, Backend-разработчики могут разрабатывать его логику работы - реализацию, скрытую за названиями методов + JSON.
Это возможность параллельной и независимой работы двух разработчиков!

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

+ До начала любых действий с кодом обсудить API: что и Backend-, и Frontend- разработчики верно понимают процесс обмена данными и тот объем, в котором их надо передавать и получать.

Продолжение 👇

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

Например, банковское приложение может получать сведения о штрафах ГИБДД из внешней системы по REST API.

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

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


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

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

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

⚡️ Новый проект: мобильное приложение G-Food для подсчета калорий ⚡️
📚 Навык: Проектирование REST API 📚

Переходим от теории к практике! Лучше всего разбираться что из себя представляет процесс проектирования REST API на примерах. Поэтому мы берём в работу задачу на разработку мобильного приложение для подсчета калорий.

Основные функции:
🔹 Добавление блюд и продуктов из базы данных для учета суточного потребления калорий. Поддержан поиск по названию и по штрихкоду. Есть возможность редактировать ранее введенные данные. (а)
🔹 Отображение истории пользователя по калориям за каждый день. (б)
🔹 Отображение пользователю текущего общего количества калорий за день. (в)
🔹 Приложение могут использовать только зарегистрированные пользователи. (г)
🔹 Отслеживание потребления воды - указание количества стаканов воды. (д)
🔹 Ведение базы данных продуктов и блюд. Если при поиске продукт не найден, то его можно создать. (е)
🔹 Рекомендации по суточному потреблению калорий в зависимости от роста, веса и возраста. (ж)
🔹 Советы по здоровому питанию. (з)

💫 Для вдохновения - аналогичные приложения на рынке:
+ YAZIO ( iOS / Android )
+ MyFitnessPal ( iOS / Android )

🔺 Старт:
Мы с вами будем работать как аналитики в Backend-команде.
Считаем, что функциональные и нефункциональные требования от заказчика собраны, БД спроектирована, дизайн UI для экранов веб- и мобильных приложений сделан.
Задачи в Jira на аналитику по созданию контрактов отдельных методов REST API готовы. Мы будем последовательно брать их в работу.

🔺 Наша цель, как системных аналитиков:
Создать контракты методов REST API для G-Food.

Welcome to the New Project 👋

#RESTAPI_getanalyst

📋 План работы с REST API на проекте G-FOOD:

1. Определить базовый URL, по которому мы будем обращаться к методам REST API.
2. Определить список методов к реализации.
3. Определить требования к безопасности (авторизации).
4. Общие требования к обработке ошибок, заголовкам запросов, именованию методов, версионированию API, к JSON-структуре запросов и ответов.

5. Далее последовательно, для каждого выбранного метода, определить и зафиксировать в документации:
5.1. тип метода: GET, POST, PUT, PATCH, DELETE.
5.2. название метода - эндпоинт.
5.3. требования к авторизации.
5.4. запрос: заголовки (headers), query-параметры, тело (body).
5.5. успешный ответ: HTTP-код ответа, тело (body).
5.6. обработка ошибок: HTTP-код ответа, заголовки (headers), тело (body).
5.7. алгоритм работы (этот пункт следует описывать раньше в задачах со сложной логикой).


👉 Функции, которые я хочу взять в работу первыми: г,в,е.

Я вижу такой порядок реализации функций в G-Food:
🔹 Приложение могут использовать только зарегистрированные пользователи. (г)
🔹 Отображение пользователю текущего общего количества калорий за день. (в)
🔹 Ведение базы данных продуктов и блюд. Если при поиске продукт не найден, то его можно создать. (е)
🔹 Добавление блюд и продуктов из базы данных для учета суточного потребления калорий. Поддержан поиск по названию и по штрихкоду. Есть возможность редактировать ранее введенные данные. (а)
🔹 Отображение истории пользователя по калориям за каждый день. (б)
🔹 Рекомендации по суточному потреблению калорий в зависимости от роста, веса и возраста. (ж)
🔹 Отслеживание потребления воды - указание количества стаканов воды. (д)
🔹 Советы по здоровому питанию. (з)


Пишите в комментариях, какой порядок реализации функций для этого приложения видите вы? Поставлю 👍 на комментарий, если допустимо, и дам обратную связь, если будут ошибки)) Можно в одном сообщении предложить несколько вариантов.

⚡️ Шаг 1. Определить базовый URL, по которому мы будем обращаться к методам REST API.

Базовый URL в REST API – это основной адрес, с которого начинается вся структура запросов к API. Он определяет место, где располагается вся функциональность API в Backend-приложении (приложении сервера).

Разберем пример метода REST API:
------------------------
GET https://test.com/api/api-name/1.0/objectName/{objectNameId}
------------------------

🗝 GET - тип метода.
Это не часть URL. Он должен забирать на себя глагол действия. Это будем разбирать на этапе проектирования конкретных методов.

🗝 https - протокол.
Обычно это "http" или "https", которые определяют способ передачи данных между клиентом и сервером. "https" обеспечивает защищенное соединение с помощью шифрования.

🗝 test.com - доменное имя (или IP-адрес).
Это адрес сервера, на котором размещается REST API. Например, "api.example.com" или "192.168.1.100".

🗝 /api - путь к ресурсу, имя каталога на сервере.
Представьте, что отсюда начинается путь к папке в компьютере. api указывает, что мы обращаемся к методам АПИ на сервере. Этот указатель в пути полезен, когда на этом же адресе также работает сайт системы или веб-приложение.
Рекомендовано указывать, но не обязательно.

🗝 /api-name - путь к ресурсу, имя папки с группой API-методов в сервер-приложении или название сервиса / микросервиса.
Примеры:
public - методы публичного API в системе,
admin-api - методы административного API для управления системой,
payment-service - API платежного микросервиса.
Рекомендовано указывать, но не обязательно.

🗝 /1.0 - путь к ресурсу, версия API.
Версия API. Может быть указана в виде /v1, /v1.0 и т.д. Цифра версии обновляется каждый раз при выпуске изменений в API, которые меняют структуру запроса или ответа JSON, или вносят другие несовместимые изменения.
Настоятельно рекомендуется указывать, чтобы не сломать текущие приложения, которые уже используют API.

🗝 /objectName/{objectNameId} - путь к ресурсу, конкретный эндпоинт.
Это часть URL, которая определяет конкретный ресурс (объект данных) или метод API, с которым клиент хочет взаимодействовать. Например, /users, /book или /product/123. Не относится к базовому URL, но является частью URL.


Базовый URL для разобранного метода REST API:
https://test.com/api/api-name/1.0/


Пишите в комментарии варианты по базовому URL для G-Food! Поставлю 👍 на комментарий, если допустимо, и дам обратную связь, если будут ошибки)) Можно в одном сообщении предложить несколько вариантов.

«Если видите над собой финансовый потолок, и вам кажется это предел, то будьте уверены — это уже чей-то пол».
Мне очень нравится эта цитата.

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

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

Если вы сейчас в этой точке, значит, вам точно есть куда расти!

Важно смотреть шире на рабочие процессы и анализировать, где можно прокачать навыки, чтобы стереть эти границы «потолка».

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

Набирайтесь сил на выходных после первой рабочей недели и не бросайте цели, которые поставили на Новый год. Идите вперёд! Всё получится!

Привет-привет! 😉 Начинаем неделю с проверки ДЗ по REST API.

В конце прошлой недели я дала теорию и задание по проектированию URL для приложения для подсчета калорий G-FOOD.

Вот что получилось.

▫️ 1. https://g-food.com/api/calories/v1/{endpoint}
Хороший вариант, если мы держим в уме, что административный API реализуется отдельно (например, для управления записями в базе о продуктах или для блокировки подозрительных пользователей, кто засорят базу).


Единственное, что мне не нравится - название API - calories. Мы же не только про калории методы даем, но и про управление базой данных продуктов. Эта часть в названии API творческая. И я бы подумала над более общими названиями.

Ошибок нет, только рекомендации!


▫️ 2. https://g-food.com/api/products/v1/… и https://g-food.com/api/dishes/v1/…
Тоже хороший вариант. Но те же самые комментарии, что и в предыдущем предложении.

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

3. Лучший вариант по продуманности!
▫️ https://g-food.com/api/products-management/1.0/ - данный путь будет содержать все endpoint для управления продуктами
▫️ https://g-food.com/api/users-management/1.0/ - данный путь будет содержать все endpoint для управления пользователями
▫️ https://g-food.com/api/statistics-management/1.0/ - данный путь будет содержать все endpoint для управления статистикой употребления пищи и воды

Продумано, что есть разные части приложения! Хорошие названия, но дублирующееся слово management кажется избыточным.

Можно заменить его сокращением или попробовать такой облегченный вариант:
https://g-food.com/products-api/1.0/



Какой URL берем, если все правы? И как придумать правильный URL для REST API? Какой порядок действий? 🧐

Продолжим в следующем посте 👇

Как придумать URL для REST API? Какой порядок действий? 🧐

В первую очередь пройдитесь еще раз по теории. Уточнения к ней:

1. http или https - зависит от наличия SSL-сертификата для домена (имени сайта).

2. Далее - название домена, который купили для приложения. Он может совпадать с доменом сайта, а может быть отдельный, при желании. Обычно он один.
У нас будет g-food.com.

3. api - необязательная стандартная часть. Можно добавлять, а можно нет. Я предпочитаю использовать, чтобы четко выделять каталог API и указывать, что мы выходим за пределы страниц сайта.

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

5. Версионирование - более или менее стандартная часть. Обычно для API делают 1.0, v1.2, v1 и подобное. Выбор за вами, не самое критичное, но настоятельно рекомендуемое (обязательная часть в URL). Дополнительно рекомендую почитать про версионирование приложений - пункт 2.

Мой вариант, который мы возьмём в работу:

🟩https://g-food.com/api/public/1.0/ - публичный API, который будет использоваться для пользовательских мобильных приложений. Основной URL, с которым мы будем работать далее.
🟩https://g-food.com/api/management/1.0/ - API для администрирования данных приложения, как блокировка пользователей, получение отчетности и другие действия со стороны владельцев приложения, которые недоступны для обычных пользователей.


Есть ли еще крутые варианты?
Да. Но мне нравятся такие.

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

Можно было бы сделать вместо одного public API несколько?
Да, можно, но выбор пока сделан так.


Готовы идти дальше? 🔥

Как понять какие задачи ставить на Backend-разработчиков по разработке API? 🧐
Определить список методов к реализации.


Каждый метод в REST API - это как правило одна задача на одного разработчика Backend. Чтобы определить этот список задач, нужно проработать функциональные требования, дизайн UI, БД.


-----

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

У нас, у аналитиков, такая же проблема в дизайне REST API. Самое сложное - описать первый метод для управления данными о каждой новой сущности - объекте данных. Остальное проще.


Пример:
🔺Создать продукт - берем первым в работу и он будет сложный.
🔺Посмотреть список продуктов - начиная с этого всё будет в 2 раза легче минимум, гарантия 80%)))) Бывают исключения со сложной логикой.
🔺Получить детальную информацию о продукте.
🔺Изменить продукт.
🔺Архивировать продукт.
(P.S. - CRUD-модель помогает мне)


Почему так?
Нужно пройти 7 кругов ада много согласований с командой по поводу названия метода для URL (endpoint - уже касались выше, но пока не внедряли) и JSON. Это обычно много споров и уточнений. Далее разработчикам надо заложить каркас под этот первый метод.

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

-------


Но вернемся к текущему моменту. У нас нет выбранных методов API к разработке. По требованиям мы определили функциональность, с которой мы работаем в G-Food в первом приоритете:

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

Какие методы будем делать? Голосуйте за верные ответы в опросе внизу. А если не нашли какого-то метода к реализации - пишите в комментарии! Ответы и комментарии завтра 😉