SkillMatch_API_контракт_презентация (1)

1.

ИТ-ПРАКТИКУМ · SKILLMATCH
API-контракт
проекта SkillMatch
Практика 2 · Endpoint’ы, параметры, ответы и ошибки
ТГУ · Проектная работа

2.

Цель и границы API
Что решает API
Что описываем
Общие правила
Обеспечивает обмен данными
между клиентским
приложением и Backend.
Методы и пути, параметры,
JSON-тела, успешные ответы и
ошибки.
REST · JSON · версия /api/v1 ·
Bearer Token для защищённых
запросов.
Рабочее допущение о предметной области
В презентации-задании не раскрыта бизнес-логика SkillMatch. Для примера предполагается, что
сервис помогает пользователям указывать навыки, находить подходящих людей и отправлять
запросы на взаимодействие.
02

3.

Выбранные пользовательские сценарии
01 · Профиль
02 · Навыки
Создать или обновить данные пользователя
Сохранить навыки и уровень владения
03 · Поиск совпадений
04 · Запрос на связь
Найти пользователей по навыкам и городу
Отправить выбранному пользователю запрос
03

4.

Endpoint 1 · Профиль пользователя
PUT /api/v1/users/me/profile
{
"displayName": "Иван",
"city": "Томск",
"about": "Изучаю программирование"
Назначение: сохранить или обновить
профиль текущего пользователя.
Поля запроса
}
• displayName — string, required, 1–50 символов
• city — string, optional, до 100 символов
• about — string, optional, до 500 символов
• Authorization: Bearer <token> — required
Ответ и ошибки
200 OK · 400 Bad Request · 401 Unauthorized · 500 Internal
Server Error
04

5.

Endpoint 2 · Навыки пользователя
PUT /api/v1/users/me/skills
{
"skills": [
{"skillId": 12, "level": "INTERMEDIATE"},
{"skillId": 27, "level": "BEGINNER"}
]
Назначение: сохранить полный список
навыков текущего пользователя.
• skillId — integer > 0, required
}
• level — enum: BEGINNER / INTERMEDIATE /
ADVANCED
• skills — array, required, не пустой
• Требуется Bearer-токен
Ответ и ошибки
200 OK · 400 Bad Request · 401 Unauthorized · 404 Not Found
05

6.

Endpoint 3 · Поиск совпадений
GET /api/v1/matches
Назначение: найти подходящих пользователей
по фильтрам.
GET /api/v1/matches?city=Tomsk
&skillId=12&page=1&size=20
{
"items": [
{
"userId": 208,
"displayName": "Алексей",
"matchScore": 92
}
],
"page": 1,
"size": 20,
"total": 1
• skillId — optional, integer > 0
• city — optional, string
• minLevel — optional, enum уровня навыка
• sort — optional: relevance (default) или name
• page — integer ≥ 1; size — 1–50
• Authorization: Bearer <token>
}
Ответ и ошибки
200 OK · 400 Bad Request · 401 Unauthorized · 500
06

7.

Endpoint 4 · Запрос на взаимодействие
POST /api/v1/connection-requests
Назначение: отправить запрос выбранному
пользователю.
{
"recipientUserId": 208,
"message": "Привет! Обсудим проект?"
}
• recipientUserId — integer > 0, required
• message — string, optional, до 500 символов
• Authorization: Bearer <token> — required
• Idempotency-Key — рекомендуется
Ответ и ошибки
201 Created · 400 Bad Request · 401 Unauthorized · 404 Not
Found · 409 Conflict · 500
Повтор с тем же Idempotency-Key не создаёт
вторую заявку.
07

8.

Единый формат ошибок и статусы
400 · Bad Request
401 · Unauthorized
403 · Forbidden
Неверные параметры или тело
запроса
Пользователь не
аутентифицирован
Пользователь вошёл, но не
имеет прав
404 · Not Found
409 · Conflict
500 · Internal Server Error
Ресурс не найден
Конфликт состояния или
дубликат
Непредвиденная ошибка
сервера
{"code":"VALIDATION_ERROR","message":"Проверьте поля",
"details":[{"field":"email","reason":"invalid_format"}],
"traceId":"7f3a91c2"}
08

9.

Авторизация и идемпотентность
Аутентификация
Авторизация
Authorization: Bearer <token>
Сервер проверяет, кто выполняет запрос. Если
токена нет или он недействителен — 401.
Проверяется право на действие. Например,
пользователь может изменять только
собственный профиль. При запрете — 403.
Идемпотентные операции
POST-запрос
PUT обновления профиля и навыков можно
безопасно повторять: итоговое состояние не
меняется от одинакового запроса.
Отправка запроса на связь может создать
дубликат. Idempotency-Key позволяет вернуть
результат первой операции.
09

10.

Последовательность работы и итог
1
Авторизация
→
2
Заполнение
профиля
→
3
Добавление
навыков
→
4
Поиск
совпадений
→
5
Отправка
запроса
Результат проектирования
• Описаны 4 ключевых сценария и соответствующие REST endpoint’ы.
• Для запросов определены параметры, JSON-структуры, успешные ответы и ошибки.
• Зафиксированы правила доступа, пагинации и защиты от повторных операций.
• Следующий шаг — оформить те же схемы в OpenAPI и проверить их через Swagger UI.
10