RESTful API и связанные ресурсы - PullRequest
Новая
       4

RESTful API и связанные ресурсы

5 голосов
/ 24 января 2020

Я разрабатываю свой первый API-интерфейс RESTful, который (к сожалению) выполняется в уже существующей системе, и идея состоит в том, чтобы разрешить третьим сторонам доступ к этой системе.

Все было хорошо, пока я не понял, что у меня есть несколько способов доступа к одним и тем же ресурсам. Я попытаюсь объяснить это, используя одну из частей системы. Система была построена с использованием Laravel 5.8 и имеет, среди прочего, следующие таблицы базы данных:

  • пользователи
  • электронные письма
  • смс

Каждый пользователь может иметь много электронных писем, и каждое электронное письмо принадлежит только одному пользователю. То же самое относится и к текстовым сообщениям.

Я «проигнорировал» весь текущий код, потому что он не был построен должным образом, чтобы сделать его RESTful API, поэтому я создал новую папку Api и весь мой код там есть.

Я думал, что было бы целесообразно иметь следующие конечные точки 

/api/v1/users
/api/v1/users/1
/api/v1/users/1/emails
/api/v1/users/1/emails/1
/api/v1/users/1/sms
/api/v1/users/1/sms/1

Таким образом, я могу получить список пользователей, получить все подробности пользователя, получить список сообщений электронной почты / текстовых сообщений, а также получить все детали определенного c сообщения электронной почты / текстового сообщения. Однако одним из требований является наличие страницы со списком сообщений электронной почты / текстовых сообщений, поэтому имеет смысл иметь: 

/api/v1/emails
/api/v1/emails/1
/api/v1/sms
/api/v1/sms/1

Чтобы не иметь 2 конечных точек для получения одного и того же ресурса (/api/v1/users/1/emails/1 и /api/v1/emails/1 вернут письмо с идентификатором 1) Я собираюсь избавиться от глубоких конечных точек /api/v1/users/1/emails и изменить их на что-то вроде /api/v1/emails?user_id=1.

Это противоречит принципам RESTful? Я не смог прийти к выводу о том, что у меня есть две конечные точки для доступа к одному и тому же ресурсу, но это «не правильно». С другой стороны, наличие /api/v1/emails?user_id=1 может вызвать некоторые проблемы безопасности / конфиденциальности (например, мне нужно убедиться, что пользователь 1 может получить доступ только к /api/v1/emails?user_id=1, а не /api/v1/emails?user_id=2), но кажется более гибким, потому что я могу его использовать один для получения всех ресурсов или с помощью фильтра user_id для получения только указанных c ресурсов.

Существует ли соглашение для этого случая?

1 Ответ

1 голос
/ 24 января 2020

Это может помочь понять, как мы понимаем «ресурсы» в контексте REST.

Любая информация, которая может быть названа, может быть ресурсом: документ или изображение, временная служба (например, «сегодняшняя погода в Лос-Анджелесе»), набор других ресурсов, не виртуальный объект (например, человек) и так далее. Другими словами, любая концепция, которая может быть целью гипертекстовой ссылки автора, должна вписываться в определение ресурса. 

/api/v1/users/1/emails
/api/v1/emails?user_id=1
/66eb6757-254e-49b4-bc8a-d04330f4482e

REST обрабатывает идентификаторы как семантически непрозрачные - клиенты общего назначения делают не используйте написание идентификатора, чтобы понять, что происходит. Рассмотрим веб-браузер - он знает, что http://example.org/cat.jpg является изображением не потому, что jpg, а потому, что img.

Это означает, что сервер может использовать любое написание, которое ему нравится - любую информацию, закодированную в Сам URI выполняется по усмотрению сервера и для его собственного использования.

Это не означает, что использование «угадываемых» написаний не дает никаких преимуществ; только то, что REST полностью зависит от того, должны ли идентификаторы быть угаданными.

Выбор написания для ваших идентификаторов, которые делают вашу реализацию проще, полностью в пределах границ.

...