REST API Дизайн ссылок между наборами ресурсов

Я обдумывал правильный метод определения наборов ресурсов, которые имеют взаимозависимость.

Например, давайте рассмотрим «документы» и «комментарии», которые независимо доступны через URI :

/documents/{doc-uri}
/comments/{comment-id}

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

Я вижу несколько основных вариантов:

1. )Укажите uri коллекции после uri документа для комментариев

GET /documents/{doc-uri}/comments/

2. )Предоставьте параметр коллекции комментариев для выбора по документу

GET /comments/{comment-id}?related-doc={doc-uri}

3. )Используйте согласование контента, чтобы запросить возврат связанных комментариев через заголовок Accept.

// Get all the comments for a document
GET /documents/{doc-uri} Accept: application/vnd.comments+xml
// Create a new comment
POST /documents/{doc-uri} Content-Type: application/vnd.comment+xml <comment>...</comment>

Преимущество метода 1 состоит в том, что комментарии автоматически помещаются в контекст документа.Что также удобно при создании, обновлении и удалении комментариев с помощью POST/PUT. Однако он не предоставляет глобального доступа к комментариям вне контекста документа. Итак, если мы хотим выполнить поиск по всем комментариям в системе, нам понадобится метод #2.

Метод 2 предлагает многие из тех же преимуществ, что и #1, однако создание комментария вне контекста документа не имеет смысла. Поскольку комментарии должны быть явно связаны с документом.

Метод 3 интересен с точки зрения GET и POST/create, но становится довольно сложным с обновлением и удалением.

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

Я рассматриваю возможность использования обоих методов 1 и 2, таким образом, я могу предоставить все необходимые функции, но я обеспокоен тем, что могу -усложнить/дублировать функциональность.