Этот вопрос является чрезвычайно открытой дискуссией, и он действительно зависит от того, как разные инженеры интерпретируют стандарты REST и лучшие практики. Тем не менее, как инженер-программист с достаточным опытом разработки сервисов REST (и профессионально сталкивался с теми же вопросами, что и вы), я бы добавил сюда свои комментарии.
Правила разработки службы REST сильно зависят от определений URL-адресов. Очень важно, чтобы вы раскрывали свой API таким образом, чтобы ваши клиенты могли точно понять, что происходит с каждым API, просто взглянув на определение URL.
При этом разные клиенты (и, если на то пошло, разные инженеры) по-разному относятся к лучшим практикам. Например, если вы пытаетесь найти пользователя по электронной почте, есть как минимум два подхода.
1) GET /users/emails/{email}
// Клиент может интерпретировать это как "получение пользователя по электронной почте"
2) GET /users?email={email}
// Клиент может интерпретировать это как "поиск пользователя по электронной почте" из-за параметра запроса
3) GET /users/email={email}
// Это можно интерпретировать так же, как # 1
Это зависит от разработчика, как он хочет представить этот API и как он документирует его для клиентов. Все подходы правильны с разных точек зрения.
Теперь конкретно по вашим вопросам. Вот как будет выглядеть мой подход с точки зрения «User
», «Student
» и «Teacher
».
Я смотрю на каждый из этих 3-х как на отдельные ресурсы? Почему? потому что это отдельные типы, хотя 2 из них расширены из 3-го. Теперь, как мой API будет выглядеть для них?
Для студента:
1) Получение списка студентов: GET /students
2) Получение студента с идентификатором: GET /students/{id}
3) Создание ученика: POST /students
4) Обновление учащегося: PUT /students/{id}
5) Удалить учащегося: УДАЛИТЬ /students/{id}
6) Найдите ученика: GET /students?{whateverQueryParamsYouWantForSearch}
То же самое относится и к Учителю.
А теперь User
.
1) GET /users
: Получение списка всех пользователей (Students
и Teachers
)
2) GET /users?type={type}
: Вот кикер. Вы можете указать тип ученика или учителя, и вы вернете данные определенного типа (должным образом задокументированные, конечно).
3) POST /users?type={type}
: создать определенный ТИП пользователя (student
или teacher
)
.. И так далее.
Основное отличие заключается в том, что API с корневым URL-адресом /users
может использоваться для ОБОИХ типов пользователей (при условии, что тип всегда указывается и документируется для клиентов). В то время как API Student
и Teacher
специфичны для этих типов.
Мои деньги всегда были на определенные типы, в то время как общие типы для поиска (имеется в виду поиск обоих типов пользователей .. используйте /users?params
). Это самый простой способ для клиентов понять, что происходит. Даже задокументировать их намного проще.
Наконец, поговорим о HATEOAS. Да, это часть стандартов, и рекомендуется ВСЕГДА предоставлять URL-адрес/ссылку на ресурс, который вы возвращаете, или если ваш возвращаемый объект сложен и содержит другие ресурсы, которые могут содержать ресурсы, которые сами могут быть доступны через API. Например,
/users?type=student&[email protected]
вернет всех пользователей с этим адресом электронной почты, и лучше следовать HATEOAS здесь и предоставить URL-адрес каждому возвращаемому пользователю, чтобы URL-адрес выглядел так: /students/{id}
. Вот как мы обычно обращались с HATEOAS
Это все, что я должен добавить. Как я уже говорил ранее, это очень открытая дискуссия. Каждый инженер интерпретирует стандарты по-своему, и нет ОДНОГО СПОСОБА для обработки всех вариантов использования. Есть некоторые базовые правила, и клиенты и другие разработчики будут вам аплодировать, если вы будете им следовать :)
person
shahshi15
schedule
20.07.2014