Есть ли какие-то best practices в нейминге эндпойнтов, помимо тех, что ты указал? Например, мы стараемся назвать объекты множественным числом (например, не partner, a partners; licences. accounts). В интернете куча ссылок, и все они включают разные пункты)
Наименования эндпоинтов является важной частью проектирования API.
Они должны быть:
1. Интуитивно понятными,
2. Отражать структуру данных и операции,
3. Быть единообразными.
ОСНОВНЫЕ ПРИНЦИПЫ НЕЙМИНГА:
🔘 ИСПОЛЬЗУЙ МНОЖЕСТВЕННОЕ ЧИСЛО ДЛЯ РЕСУРСОВ
❌ /account
✅ /accounts
Позволяет показать, что эндпоинт работает с коллекцией.
➖➖➖
🔘 ДЛЯ РАБОТЫ С КОНКРЕТНЫМ ОБЪЕКТОМ ИСПОЛЬЗУЙ ИДЕНТИФИКАТОР РЕСУРСА
✅ GET /accounts
# Получить список всех аккаунтов
✅ GET /accounts/{accountId}
# Получить конкретный аккаунт
➖➖➖
🔘 СТАБИЛЬНОСТЬ И ПРЕДСКАЗУЕМОСТЬ
Все эндпоинты должны следовать единой логике построения. Это снижает вероятность ошибок и упрощает использование.
➖➖➖
🔘 НЕ ИСПОЛЬЗУЙ ГЛАГОЛЫ В ПУТИ
Действия определяются через HTTP-методы (GET, POST, PUT, DELETE, PATCH), а не в самом URL.
❌ GET /getUserData
✅ GET /users/{userId}
➖➖➖
🔘 ИСПОЛЬЗУЙ ПОНЯТНЫЕ И КРАТКИЕ НАЗВАНИЯ
В названиях эндпоинтов избегай аббревиатур и жаргона.
❌ GET /usrmgr
✅ GET /users
➖➖➖
🔘 ИСПОЛЬЗОВАНИЕ ДЕЙСТВИЙ
Специфические действия через подресурсы или POST
Для операций, отличных от стандартных CRUD (Create, Read, Update, Delete), используй подресурсы:
✅ POST /accounts/{accountId}/activate
# Активировать аккаунт
✅ POST /licenses/{licenseId}/renew
# Продлить лицензию
В этом случае, запрос через POST подчёркивает действие, которое выполняется над ресурсом.
➖➖➖
🔘 МОДИФИКАЦИЯ ОТДЕЛЬНЫХ АТРИБУТОВ
Для частичного обновления используйте PATCH
✅ PATCH /accounts/{accountId}
{
"status": "active"
}