Основные рекомендации при выборе 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 💻

📌JSON и его взаимосвязь с базами данных

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

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

Пример данных в формате JSON:
{
"name": "Алексей",
"age": 30,
"isStudent": false,
"hobbies": ["футбол", "путешествия"]
}

В этом примере у нас есть:

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

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

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

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



🔗 Зависимость от БД

Когда мы говорим о "зависимости" JSON от базы данных, важно понимать, что сам по себе JSON является независимым форматом. Однако способ, каким БД обрабатывает, хранит и индексирует JSON-данные, может существенно влиять на производительность и возможности вашей системы.

Есть определенные лайфхаки по построению JSON-объектов на основе связанных в БД таблицах, которые помогают не потерять важные данные, которые надо вернуть или отправить в API.

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


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

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

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

Однако на практике чаще всего предпочитают использовать единственное число для ресурсов. Но и множественное число также активно используется!

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

Примеры:

Единственное число:
GET /task/123 - получить информацию о задаче с ID 123.
POST /task - создать новую задачу.

Множественное число:
GET /tasks - получить список всех задач
GET /tasks/123 - получить информацию о задаче с ID 123.
POST /tasks - создать новую задачу.


Множественное число представляет собой коллекцию элементов, что соответствует идеологии REST для метода добавления нового элемента в коллекцию и чтения списка - /tasks читается легче, где у вас есть коллекция ресурсов и конкретные ресурсы внутри этой коллекции.



🔍 Рекомендации по множественному числу есть в гайдлайнах:

Microsoft API Guidelines
7.4.1. POST ---> POST http://api.contoso.com/account1/servers

Google Cloud API Design Guide
Resource names ---> Example 1: A storage service has a collection of buckets, where each bucket has a collection of objects



Продолжение.... ⬇️⬇️⬇️

😰 При этом, если мы взглянем на Яндекс:

Пример с ед. числом:
https://yandex.ru/dev/rasp/doc/ru/reference/nearest-settlement
Пример с мн. числом:
https://yandex.ru/dev/market/partner-api/doc/ru/overview/express

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


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

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


‼️ Договариваемся на этот проект ‼️
Делаем как Microsoft и Google и в нашем проекте Task Management System будем использовать множественное число.
GET /tasks
GET /tasks/123
POST /tasks

P.S. Хотя я предпочитаю единственное число, для меня важнее договоренность с командой и поддержка единого подхода на протяжении всего проекта 🔑

🚒 Борьба со страхами 🚒

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

🔍 Топ-5 страхов аналитика:

1️⃣ Страх ошибиться. "А что, если мое решение по проекту окажется неверным?" - наверняка все мы хоть раз задавались этим вопросом.

2️⃣ Страх критики. Особенно от коллег или начальства. "А что, если меня не поймут или осудят, особенно за ошибки?". "Лучше оставлю своё мнение при себе, хотя знаю, что коллеги не правы и можно попробовать подойти к решению задачи по другому. Вдруг я ошибаюсь?".

3️⃣ Страх устаревания знаний. Мир IT быстро меняется, и всегда есть риск остаться позади, если не успеваешь осваивать новое.

4️⃣ Страх ответственности. Боязнь нести ответственность за проект или принятое решение.

5️⃣ Страх несовершенства. Постоянное желание сделать все идеально может замедлить процесс работы.


💡 Как преодолеть эти страхи?

👇👇👇

💡Как преодолеть страхи?

1️⃣ Принимайте ошибки как опыт. Ошибки - это лучший учитель. Из них можно извлечь уроки и не допустить их в будущем. В GetAnalyst мы просим быть смелыми, пробовать, и даем обратную связь в случае ошибок. Это безопасная площадка, где ошибаться можно, а иногда и нужно, чтобы получить комментарии по своей работе и запомнить их.

2️⃣ Помните о конструктивной критике. Если критика объективна и по делу, это поможет вам стать лучше. Примите её с благодарностью. В ином случае советую задуматься о том, а правильный ли коллектив вас окружает? Может пора менять компанию?

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

4️⃣ Сотрудничайте. Вы не одни! Работайте в команде, советуйтесь с коллегами, и вместе вы сможете добиться лучших результатов проектирования, а также перенять их опыт. Одна голова хорошо, 2+ лучше.

5️⃣ Идеальное — враг хорошего. Совершенство не всегда необходимо. Иногда не стоит бояться показывать промежуточные решения, чтобы опять же - получить обратную связь от коллег.


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

📌Пример POST в REST API: Проектирование метода REST API "Создание новой задачи"

🟢 Описание метода:

Метод предназначен для создания новой задачи в системе TMS (Task Manager System). Метод позволит пользователям добавлять новые задачи и задавать начальную информацию о них.


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

При получении запроса POST запроса на создание задачи от клиента REST API TMS на сервере (backend) должны быть выполнены следующие действия:

1. Сервер проверяет корректность данных, полученных в теле запроса Body (JSON) с описанием задачи.

2. Если данные корректны, создается новая запись в базе данных. Ей присваивается уникальный идентификатор id в формате UUID.
Если статус задачи не был передан в запросе, то по умолчанию установить значение “open”.
Все поля, которые не были переданы для создания задачи, указать значение null.

3. Сервер возвращает успешный ответ с данными о созданной задаче.

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


Обработка ошибок:

1а. Если не указано название задачи, то вернуть… .

1б. И т.д. - список требований к обработке ошибок.

-----------------------------
👇👇👇

🟢 Формат запросов и ответов:

Запрос:
POST /https://tms.com/api/v1/tasks
*Договариваемся, что у нас эндпоинты в мн. числе.

Content-Type: application/json
Body:
{
"name": "Задача №1",
"description": "Описание задачи",
"dueDate": "2023-11-01",
"priority": "high"
}


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

HTTP-201 Created
Content-Type: application/json
{
"id": 123,
"name": "Задача №1",
"description": "Описание задачи",
"dueDate": "2023-11-01",
"priority": "high",
"status": "open",
"createdAt": "2023-10-16T10:00:00Z"
}

Обработка ошибок:

1. Не передано название задачи.
HTTP-400
Content-Type: application/json
{
"message": “Задача не может быть создана. Укажите название задачи”,
“field”: “name”
}

2. …



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

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

Контракт может быть передан в документе Word или Confluence, но самый идеальный вариант, когда Вы можете передать его в виде интерактивной Postman- или Swagger-документации.

Возможно, вы уже почувствовали, насколько много деталей важно помнить при проектировании REST API. И это действительно так: за кажущейся простотой скрывается множество деталей и нюансов.

Не удивительно, что проектирование REST API стало частью технического собеседования для системного аналитика, т.к. это часть того, что происходит “под капотом” системы 🧐

🤖 ChatGPT для системных аналитиков: как искусственный интеллект может помочь в проектировании REST API 🤖

В декабре 2022 года родился помощник для профессионалов разных областей — ChatGPT. Созданный на основе знаний всего интернета, этот искусственный интеллект становится помощником и для системных аналитиков, в том числе в проектировании REST API.

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


Пример команды:

Работай как системный аналитик.
Проект - [Название проекта].
[Описание ключевых данных о проекте, важных для решения задачи].
Спроектируй метод REST API: [Название метода].
1. Сделай описание метода - что это и для чего.
2. Опиши логику его работы - алгоритм.
3. Определи формат запросов и ответов, влияние на БД.
Особенности и ограничения: [уточнение требований и особенностей системы].


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

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

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

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

Давайте сделаем это вместе!

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

Практический вебинар:

📚 Как проектировать REST API в Postman: с нуля до работающих методов
📅 25 октября, 19:00 МСК
🔗 ЗАРЕГИСТРИРОВАТЬСЯ

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

Что вас ожидает:
🔍 Знакомство с проектированием REST API и применением навыка в реальной жизни.
🛠 Практическая работа в Postman: от создания запросов до реализации рабочих методов на заглушках.
🔄 Про связь API с базами данных и другими системами.
🤖 Лайфхаки по созданию дизайна REST API.

Что я жду от вас:
✅ Готовность учиться на практике и активное участие в чате.
✅ Подготовка: ознакомление с базовыми понятиями API до вебинара в нашем Telegrm-канале.
✅ Мотивация и желание стать лучше в своей профессии.

Хотите получить новые навыки? Регистрируйтесь и приходите в онлайн 25 октября!

С нетерпением жду вас на вебинаре! ❤️️

🎯 Вижу цель - иду к ней 🎯

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

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

Поэтому, если не хочется через какое-то время оглядываться назад с сожалением, говоря:
"Почему он получил повышение/5 офферов на высокую ЗП, а я нет? 😔",
начните с формирования своего плана развития.


О чем из этого списка хоть раз задумывались? 🙂

◾️Хочется сменить проект, но на текущем месте работы нет возможности получить нужный опыт.
◾️Ничего не знаю тему. Хочу освоить, чтобы меня повысили в моей компании, или искать новую.
◾️Нужно структурировать знания и пополнить резюме новыми навыками. Чего мне еще не хватает?
◾️Хочу освоить новые инструменты для работы, что там про Postman и Swagger говорят?

Самостоятельное освоение новых навыков по теории и примерам из интернета возможно. Это может занять до года по каждому отдельному навыку: вы продолжаете читать теорию, чужую документацию, развиваете насмотренность, но обратную связь по своей работе не получаете. А потом собираете все ”шишки” на рабочем месте и пытаетесь исправлять ошибки. Это тоже работает, но медленнее.

Всегда возможны разные пути роста, шагов вперед, и решение как это делать за вами. Что бы вы не выбрали - это верный путь и он приведет к результату! Главное идти по нему, а не просто лежать в направлении! 🙂

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

У вас есть план с примерными датами по развитию в карьере? Ставьте ❤️ Думаете о нем? Ставим 🔥

🔔Заканчивается предзапись на практическую программу "Дизайн REST API".

Если вы до сих пор думаете, то сейчас есть последний шанс заполнить анкету, чтобы подключиться к программе на специальных условиях и за 2 месяца практических вебинаров онлайн, с обратной связью, освоить свой новый навык 🚀

📆Старт предобучения: 1 ноября.
🔗 Записаться на практику по проектированию REST API

Уже нет… 😅