Как придумать 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 в первом приоритете:

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

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

Для меня понимание REST API и принципов его работы, дало понимание архитектуры систем.

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

По ощущением это было похоже, что нашла дверь в Нарнию))

Я всегда знала: одна из веток развития для системных аналитиков — это профессия архитектора. Поэтому развивалась в эту сторону почти с начала карьеры. Понимание темы проектирования API является неотъемлемой частью работы архитектора и помогает делать шаг в эту сторону.

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


📚 Программа Дизайн REST API

🗓 ДО 21 ЯНВАРЯ заполните анкету предзаписи, чтобы забронировать место на курсе на специальных условиях.
Всего мест с практикой будет 10.


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

Развивайте hard-skills и ставьте достижимые цели в карьере. Это всегда актуально, особенно сейчас, когда в нашу жизнь входит ИИ 😉

🧩 Разбор квиза по определению списка методов REST API для проекта G-Food = ПРО ЛОГИКУ АНАЛИТИКА В РАБОТЕ С BACKEND 🧩

В первую очередь, прежде чем определить список методов, я обычно представляю себе список экранов, которые будут в мобильных приложениях пользователей. В нашем случае это КЛИЕНТЫ API.

Вопрос 1. Какие методы REST API могут использоваться для регистрации и авторизации пользователей в приложении G-Food?

(1) Экран регистрации, если нет учетной записи.
(2) Экран подтверждения учетной записи сразу после регистрации - ввод 6-значного кода из email или SMS.
(3) Экран авторизации - ввод логина и пароля.
(4) Главный - отображение актуальных калорий за сутки, сразу после входа, с базовой информацией о пользователе (например, фото и имя).
(5) Настройки учетной записи.
(6) Выход из учетной записи.


С учетом этого набора экранов разбираем ответы:

➖ Получение формы регистрации
Для регистрации всегда используется стандартный набор полей, который отрисовывается на стороне КЛИЕНТА, разработчиками фронтенд. Это требования к мобильному приложению. Backend не отвечает за визуализацию полей формы регистрации.

➕ Создание нового пользователя (Экран (1))
Метод нужен для создания данных о новых пользователей - их регистрации в системе.
Не хватает метода для экрана (2), чтобы переводить учетную запись из статуса “Новая” в статус подтвержденная. Я добавила этот экран в требования, чтобы показать, что бывает регистрация в несколько этапов. Это может быть
➕➕ Метод активации учетной записи для экрана (2).

➕➖ Удаление регистрационных данных
Необязательный метод, но сделать можно, чтобы удалять неактивированные учетные записи и очищать БД от лишних данных. ВАЖНО! Будет вызываться сервером по расписанию, чтобы пройти по списку созданных учетных записей в статусе “Новая, не подтвержденная” и удалить их.

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

➖➕ Отправка данных для входа
Если речь идёт о методе авторизации, то этот метод нам подходит. Но у нас ниже есть явный метод авторизации и в рамках него будут отправляться данные для входа. Ответ верный, но дублирует один из ответов ниже 🙂

➕ Получение списка пользователей
Для приложения администратора будет полезно, но не для приложения пользователя.

➕ Получение информации о пользователе
Метод нужен для экрана (4) и для приложения администратора.

➖ Получение полной информации о пользователе, включая пароль.
Пожалуйста, не надо пароль в чистом виде возвращать из БД через API 😥 И в шифрованном тоже. Безопасность 📉

➕ Авторизация пользователя
Нужен для экрана (3). Также в результате авторизации будет получен токен (секретный ключ), который будет использоваться для подписания всех остальных запросов к API от имени авторизованного пользователя.

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

➕➖ Удаление учетной записи пользователя
Похоже, что дублируется с методом удаления регистрационных данных. Суть та же. И чего, как мне кажется явно забыли:
➕➕Метод блокировки активного пользователя.

➕➕ Для выхода из учетной записи - экран (6), нужен метод выхода из учетной записи.
Нельзя просто выйти на экран авторизации. Нужно явно деактивировать текущий токен пользователя (секретный ключ для авторизации всех его запросов).


Этот пример описан, чтобы показать вам, как работают аналитики на проекте с API на ранних этапах: определение отдельных задач по методам REST API на разработчиков Backend на основании общих требований.

Это самая сложная и творческая часть работы, основанная на логике и опыте аналитика 💪

🧩 Разбор квиза = ПРО ЛОГИКУ АНАЛИТИКА В РАБОТЕ С BACKEND 🧩

Какие методы REST API могут использоваться для работы с базой данных продуктов и блюд в приложении G-Food?

Как прокомментировали пост “все?”. Почти 🙂 Все методы могут использоваться и пользователями, и в приложении администратора системы.

Разбор вариантов ответов:

➖➕ Поиск продуктов
Может быть реализован отдельный метод на поиск с большим количеством фильтров. Но в нашем проекте это может быть избыточно, так как нам достаточно фильтров по названию и штрихкоду.

➕ Получение списка продуктов
Благодаря этому методу можно и получать список продуктов и искать их благодаря фильтрам в параметрах запроса REST API. Как? Разберем на этапе проектирования структуры метода.

➕ Добавление нового продукта

➖➕Поиск блюд
А давайте не будем плодить сущности? ПРОДУКТ = БЛЮДО. Делаем либо продукты в системе, либо блюда. Что-то одно. По логике мне видится, что продукт более общее слово для нашей системы учета калорий. Т.к. можно съесть банан, а можно салат Цезарь 200г 🙂


➖➕Добавление нового блюда

➕Обновление продукта

➕Удаление продукта из базы данных
Только если не использовался никем из пользователей. Иначе это будет изменение признака видимости продукта в списке.

➕Получение детальной информации о продукте

➖➕Обновление информации о блюде

➖➕Получение детальной информации о блюде


По второму вопросу голосование оставлю открытым! Жду изменений в статистике ответов! Дам комментарии вместе с шаблоном требований на постановку задачи завтра 🙂

Вы любите американские горки? 😃

Это круто! Но только если мы говорим про аттракционы, а не про эмоциональное состояние, которое меняется от любого шевеления воздуха 😮‍💨

😒 То хочется уволиться, то всё-таки решил остаться.
😒 Доход то устраивает, то нет.
😒 То хочется всё бросить и уехать в деревню, то снова «на коне».

Жизнь на американских горках это то грустно, то радостно. То густо, то пусто. То получилось, то не получилось.

Чтобы настроение и страхи нас так не раскачивали нужно понимать, как с ними жить ⤵️⤵️⤵️


Как помочь себе при эмоциональных качелях?


1️⃣ Позаботьтесь о теле
Занимайтесь физическими упражнениями!

Поверьте, это невероятно улучшает настроение и уменьшает стресс.

Например, мне стоит только подумать, что сегодня лень идти на тренировку, я сразу надеваю спортивную форму и лечу в зал. Потому что знаю, тело и разум скажут позже спасибо 👌



2️⃣ Изучите эмоции

Попробуйте разобраться в том, что вызывает вас на эмоциональные качели. Попробуйте записывать свои мысли и чувства, чтобы лучше понимать своё состояние.



3️⃣ Поищите поддержку

Старайтесь не оставаться с переживаниями наедине. Не бойтесь позвонить другу и прямо сказать: «Мне нужна твоя поддержка!»


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



4️⃣ Преобразуйте образ жизни

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


5️⃣ Не сдавайтесь

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



Каждый из нас уникален, и каждому может подойти разный способ! Главное — принять это и попробовать найти свой метод борьбы с эмоциональными качелями 🙌🤍

🚀 Всё о 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, аутентификация и авторизация.

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

📌 Структура постановки задачи на REST API метод для Backend-разработчика 📌

Вариант структуры постановки задачи на REST API метод на разработчика сервер-приложения (Backend), которую можно использовать для создания документации в Confluence. Аналогичную структуру постановки задачи можно реализовать через инструменты документирования и тестирования API - Postman и Swagger.

1. Название метода
2. Общее описание
3. Алгоритм работы
4. Пример запроса
4.1. Описание эндпоинта метода и базовых параметров
4.2. Тело запроса - в JSON или в другом поддерживаемом RES API формате обмена данными.
5. Пример ответа
5.1. HTTP-Код ответа и описание
5.2. Тело ответа
6. Маппинг БД-JSON
7. Дополнительные требования

Эта структура контракта для метода REST API. которая может быть использована разработчиками Backend для реализации метода, и разработчиками клиентов API, кто будет использовать этот REST API запрос в своём приложении.

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

Подробности и примеры по каждому пункту добавила для вас в блог Структура постановки задачи на REST API метод, чтобы не теряли 😉

⚙️ Инструкция: как назвать endpoint для метода REST API ⚙️

Endpoint - полный адрес метода REST API с выбранным типом метода. Он первым идет по структуре постановки задачи на разработчика.

Пример endpoint:
Метод получения информации о продукте с идентификатором = {productId}.
GET https://g-food.com/api/public/1.0/products/{productId}
🔸 GET - тип метода - действие, которое не надо дублировать в названии endpoint.
🔸 products - объект, которым управляем.



⚙️ Инструкция:

1. Определить, какой сущностью мы управляем. Это название endpoint-а.
products - работаем с сущностью продукт.


2. Если не обращаемся к конкретному объекту, то {id} в конце нет. Иначе - есть.
▶️ GET /products/{productId} - получаем конкретный объект, т.е. конкретный продукт по id.
▶️ GET /products - получаем полный список продуктов в системе.
▶️ POST /products - создаем новый продукт в системе, пока конкретного объекта и тем более его id нет в системе, его надо создать.


3. Название endpoint-а может быть как в единственном, так и во множественном числе.
Если работаете с существующим API и разрабатываете дополнительный метод, смотрите как были сделаны остальные. Если новый, то на ваше усмотрение.
▶️ GET /product/{productId} - верно
▶️ GET /products/{productId} - тоже верно
Главное иметь договоренности. Мы с вами будем работать с множественным числом.


4. Метод может иметь вложенность.
Например - получить список фотографий продукта (только фото, без описания).
GET /products/{productId}/photos


5. Правильно выбирайте тип метода:
GET - получить
POST - создать (бывают исключения, когда “получить”)
PUT - изменить целиком, создать
PATCH - изменить частично
DELETE - удалить


❌ Не рекомендуется:

В название endpoint вставлять глагол действия - create, update и подобные.
POST /createProduct - плохо из-за слова create. Тип метода POST уже говорит о том, что мы что-то создаем. Не надо “масло масляное”.

▶️ Примеры по именованю эндпоинтов по инструкции ▶️

Мы с вами не разобрали второй вопрос квиза. Поэтому дам правильные ответы на него, и приведу названия эндпоинтов (endpoint) для методов, которые понадобятся в нашей системе 🙂


Какие методы REST API могут использоваться для работы с информацией о калориях в приложении G-Food?

➕➖ Отправка информации о сегодняшних калориях
= Добавление записи о потребленных калориях.

➕➖ Запись информации о каждом употребленном продукте в определенный день
= Добавление записи о потребленных калориях


➕➖ Обновление информации о калориях
= Обновление записи об употребленном продукте

➕➖ Обновление записи об употребленном продукте в определенный день
= Частичное обновление записи о калориях

➕Добавление записи о потребленных калориях

Метод вызывается авторизованным пользователем и позволяет считать калории за счет записи съеденных продуктов. По сути записываем калории (calories) или еду (food). Нужно выбрать одно название.

POST /food или POST /calories или POST /caloriesRecord

Последнее мне нравится больше, так как мы вносим информацию о съеденных калориях, добавляя записи о еде.

➕ Частичное обновление записи о калориях

PATCH /caloriesRecord/{caloriesRecordId}

➕Удаление записи о калориях

DELETE /caloriesRecord/{caloriesRecordId}

➕➖Удаление записи об употребленном продукте в определенный день
= Удаление записи о калориях

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


Готовы практиковаться давать названия эндпоинтам? 🙂

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

Если вы хотите освоить проектирование REST API, инструмент Swagger, используемый для создания интерактивной документации, и получить реальный опыт работы над проектом, то этот онлайн-практикум для вас!

📚 Про REST API за 2 часа: с нуля до Swagger-документации
📅 24 ЯНВАРЯ, 19:00 МСК
🔗 ЗАРЕГИСТРИРОВАТЬСЯ

План:
1. Самая важная теория по REST API и квиз для её закрепления.
2. Проектирование методов REST API с нуля.
3. Создание Swagger-документации для спроектированных методов.
4. Шаблон постановки задачи на разработку REST API-метода.

Подготовка к практикуму:
1. Зарегистрироваться в Swagger. Инструкция доступна по ссылке.
2. Прочитать базовую теорию по REST API в канале и следить за текущими публикациями.
3. В процессе онлайн-практикума работать с компьютера и быть активными в чате.


Хотите начать реальную работу с REST API?
Регистрируйтесь и подключайтесь к эфиру 24 января! 🚀🤗💪

До встречи встречи онлайн!