Не отвлекаемся, проходим мимо, фокус на работе 👩‍💻🧑‍💻🦭

Настроение понедельника 😁

🔷 Пример задачи на проектировани JSON без списков - на что обращать внимание 🔷

Как решала задачу по созданию JSON, если говорить не про собеседование, а про реальную работу:

0️⃣ Доработка БД, т.к. на UI больше данных
Мои дополнительные вводные - БД проекта.
В ней отсутствует часть данных, которые есть в UI: правила аренды, характеристики (двигатель, коробка, кол-во мест и другие).
Новые поля и таблицы надо добавить в БД.
На этом шаге JSON пока не трогаю.


1️⃣ Для этого экрана сделала основным объект “автомобиль” (car)
Перечисляю в JSON данные о нем:
- "id",
- "brand" - вложенный объект с данными из связанной таблицы БД, но можно было и упроситить,
- "class" - аналогично "brand",
- "model",
- licensePlate - есть в БД, доступен для админов, но от обычных пользователей гос. номер авто мы должны скрывать,
- "publicCode" - а вот это дизайнеры не учли, надо сообщить, чтобы добавили,
- "color" - в БД есть, а на UI нет, но поле не секретное, поэтому можно вернуть, если вдруг в будущем оно понадобится,
- "mileage" - на экране показано “< 50 тыс”, а в БД конкрентное число, которое обновляется каждый раз после поездок. В API можем возвращать фактическое число миль, а Frontend-разработчики пусть сами наводят красоту с “< 50 тыс” 🙂
…. и т.д.

Суть шага:
В приоритете смотрю на UI, далее делаю сверку данных UI с БД, и строю плоский список данных в формате JSON.
Если вижу связанные таблицы (внешние ключи FK в описываемой сущности), то делаю вложенные объекты в JSON, но это зависит от задачи.


2️⃣ "rentalRules" и "rentalTerms" - логически сгруппировала данные об условиях аренды в общем и для текущего запроса от пользователя.
От логической группировки можно отказаться, но кажется, что это делает структуру более удобной для чтения.


3️⃣ Рассчеты цен делает алгоритм REST API метода, чтобы не дублировать сложные расчеты в разных Frontend.


Есть ли еще варианты для JSON? Да.

Это один из тех, которые выбрала я, зная БД и UI всех приложений, в которых понадобится аналогичный JSON-объект данных car (автомобиль).


#RestApiGA

🔷 Пример задачи на проектировани JSON - массивы [] 🔷

Списки обычно нужны при получении данных. Но иногда и для других операций.

Когда мы работаем со списками, то при проектировании JSON обращаем внимание на следующее:
1. Есть список - нужна или понадобится пагинация (limit, offset, count).

2. Название списка - рекомендуется множественное число ("cars": []).

3. Список содержит меньше элементов, чем полный объект car, поэтому возвращаем необходимый и достаточный минимум в ответе API (всё, что связано с отображаемыми данными на карточках + с фильтрами).

4. Чем меньше вложенных структур у элементов {} внутри списка [], тем лучше. Убирать лишнюю вложенность по воможности.

5. Рекомендуется сохранять структуру одиночного объекта JSON для удобства клиента.


👉 Пример:
Метод получения списка автомобилей

GET https://rentacar-project.com/api/public/v1/cars

Пример JSON для списка:

{ "limit": 10,
  "offset": 0,
  "count": 235,
  "cars": [
 {
   "id": "b3fd9d8c4-8f6a-4e8f-b7e9-2d8f7b9a0d4c",
   "brand": {
     "id": "f4d8e4a6-8f29-4e60-b8c7-3c6a2dbf8c61",
     "name": "Mercedes-Benz"
   },
   "class": {
     "id": "d5a6e4b8-9b7a-4e92-82f6-b3a6f7b8e0c5",
     "name": "Премиум"
   },
   "model": "CLA AMG",
   "publicCode": "10293847",
   "year": 2021,
   "gearbox": "auto",
   "currentRentalOffice": {
     "id": "a3b9f2d4-7b2a-41e5-8b3e-4c7d3f5e8e3b",
     "name": "Москва, Центральная",
     "address": "г. Москва, ул Центральная, 123"
   },
   "rentalTerms": {
     "startDate": "2024-10-24",
     "endDate": "2024-10-27",
     "dailyRate": 8000,
     "totalPrice": 24000
   },
   "pictureId": "e2c4d6e1-8f1e-43a9-8f2e-4d2f7b8e0b5a"
 },

 {
   "id": "d7cc0a8c4-8f6a-4e8f-b7e9-2d8f7b9a0d6d",
   ...
   ...
   ...
   "pictureId": "a3b7a9e1-8f1e-43a9-8f2e-4d2f7b8e0c6d"
 }
  ]
}

#RestApiGA

🤍 Коллеги, спасибо вам за обратную связь 🤍

Каждый раз душа радуется, когда смотрю ответы в период рассылки сертификатов об окончании обучения и вручения подарков для наших самых активных участников занятий ☺️

Это слова, которые вдохновляют развивать GetAnalyst.

Ваши слова ценны для всей команды 🤍

🙌 Разбор тестирования по структуре URL 🙌

(тестирование было в понедельник)

1. Какой из следующих URL составлен больше всего подходит для получения списка доступных автомобилей для аренды?

✅ https://api.rentacar-project.com/admin/v1.0/cars?status=available - самый подходящий вариант, так как фильтр по статусу верно вынесен в состав query-параметров.

☑️ https://api.rentacar-project.com/admin/v1.0/cars/available - допустимый вариант, но плохо в нем то, что фильтров для списка авто может быть больше, и лучше всегда фильтры отправлять в query (после ?)

❌ https://rentacar-project.com/v1.0/admin/available/cars - ошибочный вариант, т.к. нарушен порядок: available не является объектом, и он почему-то впереди указателя на объект машины “cars”.

❌ https://rentacar-project.com/admin/cars/status/avallable - ошибочный вариант, т.к. сделали странное нагромождение в конструкции пути запроса, чтобы показать, что status=available (доступен)

‼️api.rentacar-project.com - префикс api перенесен в доменное имя, вместо пути. Это допустимо!

2. Какой из следующих URL является правильным примером для получения информации о конкретном автомобиле (id = 123)?

❌ https://rentacar-project.com/api/admin/v1/car/{123} - не должно быть {}, это используется только для обозначения в документации, что на это место надо подставить значение.

☑️ https://rentacar-project.com/api/admin/v1/car?carld=123 - допустимо, но когда получаем информацию о конкретном id, рекомендовано использовать не фильтры, а path-параметры.

✅ https://rentacar-project.com/api/admin/v1/car/123 - идеально, это метод GET /car/{carId}.

❌ https://rentacar-project.com/api/admin/v1/car/{carld=123} - не должно быть {}, как в=и в варианте 1 что-то странное.




3. Какой из следующих URL является некорректным для запроса списка всех автомобилей в системе?

✅ https://api.rentacar-project.com/v1.0/cars?page=2&limit=10 - допустимо, элементы пагинации page (страницы), limit (максимальное число элементов на страницу)

☑️ https://rentacar-project.com/v1.0/car/all - допустимо, хотя так крайне редко делают, часть all можно смело отбросить

☑️ https://api.rentacar-project.com/cars?v=1.0&limit=10 - можно сделать версию query-параметром. Но это такое же плохо сопровождаемое решение, как и версия api в body. Не рекомендуется, но можно. Если не нравится версия в пути, отправьте в headers. На уровне query ее могут потерять, она бросается в глаза и мешает

✅ https://rentacar-project.com/api/v1.0/cars?offset=100&limit=20 - допустимо, элементы пагинации page (номер элемента), limit (максимальное число элементов на страницу)



Продолжение следует 🙂

#RestApiGA

💥 Завершается запись на REST API на специальных условиях 💥

Предстоит менять компанию и выходить за пределы знаний о системах, с которыми работали? Нужно изучить REST API, Swagger, Postman? Этот пост для вас 🙂

Открыта запись на практическую программу:
📚 Дизайн REST API
🗓 Старт 5 ноября
❗️Следующий поток в онлайн планируется на апрель 2025.

🎁 Для всех, кто запишется на программу до 25 октября, действуют самые выгодные условия + дарим в подарок дополнительное обучение по БД+SQL.

В течение 2-х месяцев вас ждет:
◽️ 8 онлайн-встреч с опытными системными аналитиками.
◽️ Работа над ОДНИМ проектом в течение всей программы.
◽️ Детальный разбор проектирования RESTful API с нуля: от БД+UI до готовых RESTful API методов.
◽️ Практика в инструментах для тестирования и документирования REST API - 🟠Postman и 🟢Swagger.
◽️ Встреча для разбора индивидуальных проектов.


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

Самые приятные сообщения в середине прохождения программы:

Был на собеседовании и получил оффер! Спасибо!!! Все что уже изучили пригодилось. Я смог дать несколько вариантов решения задачи и объяснить, почему каждый из них подходит, какие хуже, а какой лучший

Это результаты вашей работы, которыми я восхищаюсь! ❤️

Приглашаем вас присоединиться к новой команде по работе с REST API!

Есть вопросы или не уверены, что эта программа актуальна для вас?
Пишите @getanalyst или заполняйте анкету предзаписи. Мы свяжемся с вами, поможем оценить текущие навыки и ответим на ваши вопросы! 🙂

🙌 Продолжение: Разбор тестирования по структуре URL с понедельника 🙌


4. Какой URL и метод следует использовать для добавления нового автомобиля в систему через API?

❌ GET https://api.rentacar-project.com/v1.0/cars - GET используется только для получения данных.

✅ POST https://api.rentacar-project.com/v1.0/cars - идеально подходит для создания автомобилей.

✅ PUT https://api.rentacar-project.com/v1.0/cars - метод PUT можно исользовать для методов создания и изменения данных, помогает обеспечивать идемпотентность.

❌ DELETE https://api.rentacar-project.com/v1.0/cars - DELETE используется только для операций удаления.



5. Какой URL и метод следует использовать для обновления данных конкретного пользователя с id=567?

✅ PUT https://rentacar-project.com/api/v1.0/public/users/567 - хороший вариант, PUT используется для полной перезаписи данных в БД.

✅ PATCH https://rentacar-project.com/api/v1.0/users/567 - хороший вариант, PAT CH используется для частичной перезаписи данных в БД.

☑️ PATCH https://rentacar-project.com/api/v1.0/users?userld=567 - можно, но все же указатели на объект рекомендуется держать не в query, а в path-параметрах запроса.

❌ POST https://rentacar-project.com/api/v1.0/users/567 - допустимо для HTTP API, но недопустимо для RESTful API принципов.




Если пропустили тестирование и теорию в понедельник, очень рекомендую вернуться к ним.

Важная теория:
📌 Типы методов
📌 Структура URL
📌 Идемпотентность в API (подкаст)


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

#RestApiGA