API de REST Diseñar enlaces entre colecciones de recursos

Question

He estado reflexionando sobre el método correcto para definir colecciones de recursos que tienen interdependencia.

Por ejemplo, vamos a considerar "documentos" y "comentarios" que son independientemente accesible a través de la URI de:

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

Sin embargo, por lo general queremos la colección de comentarios relacionados con un documento específico. Lo cual crea una pregunta de diseño sobre cómo debe ser arqueado esto.

puedo ver algunas opciones principales:

1.) suministrar una URI de semen después de la URI documento para comentarios

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

2.) Proporcionar un parámetro a la colección de comentarios para seleccionar por documento

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

3.) Utilice la negociación de contenido para solicitar que los comentarios relacionados se devuelvan a través del encabezado Aceptar.

// 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> 

El método 1 tiene la ventaja de colocar automáticamente los comentarios en el contexto del documento. Lo cual también es bueno cuando se crean, actualizan y eliminan comentarios usando POST/PUT. Sin embargo, no proporciona acceso global a los comentarios fuera del contexto de un documento. Entonces, si quisiéramos hacer una búsqueda sobre todos los comentarios en el sistema, necesitaríamos el método n. ° 2.

El método 2 ofrece muchos de los mismos beneficios que el # 1, sin embargo, crear un comentario sin el contexto de un documento no tiene sentido. Dado que los comentarios deben estar explícitamente relacionados con un documento.

El método 3 es interesante desde una perspectiva GET y POST/create, pero se pone un poco complicado con la actualización y la eliminación.

Puedo ver los pros y los contras de todos estos métodos, así que estoy buscando más orientación de alguien que puede haber abordado y resuelto este problema antes.

Estoy considerando hacer ambos métodos 1 & 2, así puedo proporcionar todas las funcionalidades necesarias, pero me preocupa que pueda estar sobre-complicando/duplicando la funcionalidad.

Answer 1

API de REST debe estar controlado por hipermedio. Consulte Hypermedia como la restricción del motor del estado de la aplicación (HATEOAS). Por lo tanto, no pierda su tiempo en los patrones URL, porque no son RESTful. URLPattern implica un acoplamiento cerrado entre un cliente y un servidor; simplemente, el cliente debe ser consciente de cómo se ven las URL y tiene la capacidad de construirlas.

consideran este diseño de descanso para sus casos de uso:

La representación de un documento contiene un enlace donde el cliente puede enviar comentarios o con el uso de llegar llegar todos los comentarios sobre el documento. p.ej.

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

Un cliente solo toma esta URL y realiza el método GET o POST en la URL; sin saber cómo es la URL, parece.

Ver también este post:

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

Answer 2

La combinación de los métodos 1 y 2 se ve bien, como se dice en el método 2, no tienen demasiado sentido crear comentarios sin un contexto documento desde una existe una relación padre-hijo entre ambos, si elimina un documento es aceptable eliminar todos sus comentarios también, puede hacer que su /comments/ uri sea un recurso de solo lectura para evitar su creación sin un documento.

Como filip26 dice que las API deben ser hipermedia pero eso no significa que los patrones de URL no sean importantes, puede tener un recurso con un uri o muchos, si sus recursos tienen múltiples uris es más fácil para los clientes encontrarlos , la desventaja es que podría ser confuso porque algunos clientes usan un uri en lugar de otro, por lo que puede usar un uri canónico para un recurso, cuando un cliente accede a un recurso a través de este uri canónico puede enviar un 200 OK, cuando un cliente lo solicita uno de los otros uri puede enviar un 303 "Ver también" junto con el uri canónico.