🚀 Всё о 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 января! 🚀🤗💪

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

Привет!

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

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

Этот разбор примера поможет понять, какой результат ожидать в результате проектирования, и что из себя представляет контракт REST API 😎

🚀 Пример постановки задачи на REST API 🚀

---------------
🔸 Изменение продукта - PATCH /products/{productId}
---------------

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

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

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

🔸 Логика работы:

Метод изменяет только те данные о продукте, которые переданы на вход.

Метод доступен только для авторизованных пользователей.

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

Ограничения:
- Пользователь может менять только те продукты, которые он добавил в справочник сам, но не может менять продукты, которые создали другие пользователи приложения.
- Администратор может менять все записи в справочнике.
- При сохранении изменений проверять совпадения по названию и штрихкоду. Искать в базе похожие продукты и предлагать объединить их в один, если создается дубликат.
- Если продукт уже был добавлен к кому-то в употребленное меню за день, то изменения не должны повлиять на старые записи, которые есть у других пользователей. Для этого необходимо вести версионирование информации о продукте и при изменении увеличивать версию продукта на 1.
- Если при редактировании был удален один из обязательных параметров, то вернуть ошибку сохранения. Данные не обновлять.

Клиенты:
- Мобильное приложение G-Food - экран изменения информации о продукте.
- Приложение администратора - экран управления справочником продуктов - редактирование (ссылка).

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

🔸 Пример запроса:
PATCH https://g-food.com/api/public/1.0/products/{productId}
- query-параметры: нет
- headers:
-- content-type: application/json
- authorization: token пользователя.

Рост и результаты не даются мне легко!

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

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

Не подумайте, что обесцениваю учёбу в университете: было действительно продуктивно, так как я из тех, кто делал все ДЗ и учился на 5. А за программирование, проектирование БД и UML хочу сказать отдельное спасибо! 😅

Когда я запускала GetAnalyst, мне хотелось как можно больше практики, прикладного опыта.
И я долго не понимала, как всё это идеально совместить. Чтобы аналитики отучившись сразу всё могли внедрить в работу!

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

Старт GetAnalyst ассоциируется с 10-14 часов работы в сутки, вдохновением и упорным трудом. У меня появилась цель: я не хотела от нее отказываться или откладывать, и шла к ней! Настолько быстро, насколько возможно.

До сих пор вспоминаю, как была в путешествиях, но выходила из отеля 2 раза в день: на час до спортзала, и на час погулять. А в выходные можно было работать только 4-6 часов, чтобы всё успевать. Тогда удавалось посмотреть всё что возможно за пару дней, или просто выдохнуть.

Сейчас, в январе 2024 года, я открываю телеграм-канал GetAnalyst и вижу результаты. Вас больше 5,5 тысяч! 🔥 Это небольшой футбольный стадион 😅

Вы меня читаете, приходите на вебинары, учитесь, и даёте приятную обратную связь! Это стоит всех усилий 🙌

Зачем я про это говорю? Затем, чтобы показать, как бывает.

Чтобы вырасти, требуется огромное количество сил, энергии, переживаний.
Каждый раз как из гусеницы в бабочку.
Это не бывает незаметным☝️
Без этого нет перемен, роста, новых идей и возможностей.

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

Мне хочется вас призвать:
Не стесняйтесь своих трудностей! Не думайте, что если сложно или вас кто-то не понимает, то значит нужно бросать!

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

Поддерживаю каждого, кто сейчас на стадии таких изменений 🫂 Потому что у меня опять идёт очередной рывок вперёд, и надеюсь, что уже очень скоро будет чем с вами поделиться 💫

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

А вас также хвалят на работе?😄

Завидуете коллегам, которые неуклонно развиваются в профессии? 🤔

Только честно!
Вслух можно не признаваться 😄

Порой кажется, что где-то тебя обошли вниманием, где-то не поднажал сам и «забуксовал» на одном месте.

Но я считаю, что зависть — это классное чувство. Она не должна закапывать и лишать мотивации ☝️ Это те самые маячки, которые подсвечивают нам: «хочу также»!

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

Напоминаю:
⚡️ 21 января заканчивается предзапись
🎯 Дизайн REST API - 2 месяца практики,
✅ где мы будем работать над одним проектом,
✅ чтобы с нуля описать требования к разработке.

Для кого-то из вас этот тот самый навык, который поднимет выше и придаст уверенности в своих знаниях 🙌

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

А главное - на собеседованиях по вопросам REST API вы сможете отвечать приводя реальные примеры, и покажете свои проекты из портфолио, которые мы создадим!

📌JSON - формат сообщений, используемый в REST API

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

JSON, что расшифровывается как "JavaScript Object Notation", является легковесным форматом данных, который легко читается и пишется как человеком, так и системами. Он основан на синтаксисе объекта языка программирования JavaScript, но существует независимо от языка.

Пример данных в формате JSON - объект "Пользователь":
{
"id": 1,
"name": "Степан",
"email": "stepan@email.com",
"isStudent": false,
"hobbies": ["футбол", "путешествия"]
}

В этом примере:

🔹Объект {} человека или пользователя, в зависимости от контекста системы. Всегда есть открывающаяся и закрывающаяся скобка.

🔹Пары ключ-значение: слева в кавычках ".." указывается название поля, а справа его значение. Что важно, название полей в JSON и в БД не обязательно совпадают.

🔹Показаны возможные типы данных: обратите внимание, что числа без кавычек, массивы (списки однотипных данных) в [], boolean - флаги да/нет (true/false) также без кавычек.

🔹camelCase - рекомендация по именованию полей.

JSON - стандарт в мире программирования и обработки данных. Он позволяет системам обмениваться структурированной в едином стиле информацией.


Для работы с JSON и самостоятельных экспериментов рекомендую: https://jsoneditoronline.com/

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

✔ body (тело) запроса в JSON для метода PATCH ✔

Мы создаем пример постановки задачи для разработки метода изменения продукта PATCH.

Параметры, которые нужно изменить в результате обработки запроса, обычно не передаются в составе URL-запроса (query-параметры), а передаются в теле запроса (⚡️request body). Этот подход также распространяется на POST и PUT.


Метод PATCH позволяет полностью или частично менять объект данных. Это означает, что на вход методу PATCH мы можем передать:


❌ 1. Все параметры объекта.
Это актуально для PUT, но не для PATCH. Так лучше не делать.


✅ 2. Все параметры, доступные к изменению.
Можно и допустимо. Обычно этот вариант используют в примерах API-документации.


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


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

Поэтому, для создания документации, мы будем описывать пример JSON, показывая все параметры, доступные к изменению.


Продолжение с примером JSON для PATCH /products/{productId} 👇

📌 JSON — пример запроса для шаблона документации 📌

PATCH /products/{productId} - изменение продукта для приложения подсчета калорий G-Food.

К изменению доступны параметры:
- название - "name" - строка,
- описание - "description" - строка,
- штрихкод - "barcode" - строка,
- размер одной порции (грамм) - "portionSizes” (допустимо несколько вариантов) - список с перечислением - название порции ("name") и кол-во грамм ("size"),
- количество ккал на 100 грамм - "kcal",
- белки (г) на 100 грамм - "proteins",
- жиры (г) на 100 грамм - "fats",
- углеводы (г) на 100 грамм - "carbs".

Далее мы дополнительно укажем типы данных для каждого параметра. На этапе описания маппинга.

JSON объекта будет выглядеть как:
{
"name": "Овсяные хлопья",
"description": "Хлопья из цельного овса, богаты клетчаткой и микроэлементами. \nОчень вкусные",
"barcode": "1234567890123",
"portionSizes": [
{
"name": "Маленькая порция",
"size": 30
},
{
"name": "Стандартная порция",
"size": 50
}
],
"kcal": 389,
"proteins": 13,
"fats": 6.9,
"carbs": 66.3
}


Разбирая строку "name": "Овсяные хлопья", уточняю:
🔸 "name" - ключ, название параметра в JSON. Может не совпадать с названием в БД и у тем более на UI.
🔸"Овсяные хлопья" - значение параметра. Берётся из БД, из таблицы с продуктами.



В качестве дополнительных примеров можно взять:
{
"name": "Овсяные хлопья",
"description": "Хлопья из цельного овса, богаты клетчаткой и микроэлементами. \nОчень вкусные",
}

или массив (список):

{
"portionSizes": [
{
"name": "Маленькая порция",
"size": 30
},
{
"name": "Стандартная порция",
"size": 50
}
]
}


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

Вставьте код в JSON Editor Online, чтобы проверить, что получилось 👍