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, но получает своеобразное волосатое обновление и удаление.

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

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

Ответ 1

API REST должен быть связан с гипермедией. См. Hypermedia как ограничение состояния приложения (HATEOAS). Поэтому не тратьте время на URLPatterns, потому что они не RESTful. URLPattern подразумевает жесткую связь между клиентом и сервером; просто клиент должен знать, как выглядят URL-адреса и имеет возможность их создавать.

Рассмотрим этот дизайн REST для вашего прецедента:

Представление документа содержит ссылку, в которой клиент может отправлять комментарии POST или использовать GET, чтобы получить все комментарии к документу. например.

{
  ...
  "comments" : {
      "href": ".. url ..",
      "rel": ["create-new-comment", "list-comments"]
  }
}

Клиент просто берет этот URL-адрес и выполняет метод GET или POST по URL-адресу; без знания того, как выглядит URL-адрес.

Смотрите также эту запись:

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Ответ 2

Комбинация методов 1 и 2 выглядит неплохо, как вы говорите в методе 2, не имеет слишком большого смысла создавать комментарии без контекста документа, поскольку между дочерними отношениями существует родительское дочернее отношение, если вы удаляете документ, приемлемо для удалите все его комментарии, вы можете сделать свой /comments/ uri доступным только для чтения ресурсом, чтобы избежать его создания без документа.

Как говорит filip26, rest apis должен быть обработан гипермедией, но это не означает, что шаблоны url не важны, у вас может быть ресурс с одним uri или многими, если ваши ресурсы имеют множественный uris, для клиентов легче найти их, недостатком является то, что может сбивать с толку, потому что некоторые клиенты используют один uri вместо другого, поэтому вы можете использовать канонический uri для ресурса, когда клиент получает доступ к ресурсу через этот канонический uri, вы можете отправить обратно 200 OK, когда клиент попросите одного из других uri вы можете отправить обратно 303 "См. также" вместе с каноническим ури.