Эта статья предназначения для специалистов, уже имеющих опыт разработки REST API. Большинство уже знакомы с лучшими практиками разработки REST API, но некоторые советы и популярные приемы могут оказаться не столь хорошими … Предлагаю посмотреть, как можно улучшить даже самые хорошие практики для интерфейсов, замыкающихся на объекты реляционных моделей.
Определения
/users: – маршрут коллекции
/user: – маршрут объекта
Получить пользователя по номеру телефона, почты, СНИЛС и т.д.
Если хотите получить один объект по id или ошибку 404, сделайте так …
/users/{id}:
Если хотите получить один объект по прочим уникальным ключам или ошибку 404, сделайте так …
/user: … parameters: phone, email, snils, login etc.
Если нужно получить сравнительно небольшой список по критериям выборки, то так …
/users: … parameters: …
Если список очень большой и получение предполагается в несколько итераций, то с помощью выделенной операции …
/users/list: … parameters: lastKey, limit.
Напоминание, используйте параметр fields для подрезки трафика, забирайте только нужные данные.
Не более одного параметра в маршруте
Если у вас не составной ключ, что для реляционной модели редкая редкость, то так …
Плохо:
/orders/{orderId}/items/{itemId}:
Хорошо:
/orders/items/{itemId}:
Делайте дружественный API
Если к вам будут ходить разные системы и каждая система хочет работать со своим ключом объекта – сделайте дружественное API. Полиморфность идентификатора реализуется так: