¿Cuál es la mejor estructura de URL RESTful para un recurso recursivo?

Estoy creando un servicio RESTfull para una estructura de recursos en forma de árbol y me preguntaba cuál sería la mejor estructura de URL.

Tengo tres requisitos:

ser capaz de obtener una colección de recursos raíz
ser capaz de obtener un recurso individual
ser capaz de obtener una colección de recursos secundarios

Mi pensamiento actual es:

/rest/documents
/rest/documents/{id}
/rest/documents/{id}/documents

También estaba pensando en seguir las rutas en singular / plural para denotar listas o elementos individuales, pero sé que voy a tener un recurso que es el mismo plural que singular, así que decidí no hacerlo.

¿Alguien tiene alguna idea sobre lo anterior? o tiene una forma diferente / mejor de estructurar esto?

web-services

— Matt Brailsford
fuente

Puedo estar malinterpretando la pregunta, pero como estamos hablando de URL, ¿el SEO es un problema?

— Jon Hopkins

El SEO no es un problema, no. Básicamente, estoy pidiendo la mejor estructura de URL lógica para un recurso de autorreferencia.

— Matt Brailsford, el

Eso me parece bastante sencillo.

— Tim Post

¿Qué tan profundo puede ir esa estructura?

— Martijn Verburg el

@Martijn la profundidad no está restringida

— Matt Brailsford

Respuestas:

Lo que me viene a la mente es: no permita que la API RESTful refleje la recursividad en la propia URL. Ahora que lo pienso, su recurso son solo los documentos.

Si tiene sus documentos almacenados físicamente de acuerdo con la estructura recursiva, cree una asignación a una ID única y use la ID en la URL:

/rest/documents/{id}

Ahora, si tienes tus documentos así:

El | DocumentName | DocumentPath | DocumentID |
--------------------------------------------
El | abc | / abc | 1 |
El | asd | / abc / asd | 2 |
El | asd | / asd | 3 |
El | boo | / abc / asd / boo | 4 |
El | hey | / abc / asd / hey | 5 |

la solicitud consultaría esta url para el /abc/asddocumento

GET /rest/documents/2

Por lo tanto, ahora debe proporcionar a los usuarios de su API medios para atravesar su estructura con poco esfuerzo. Eso podría hacerse envolviendo su carga útil de respuesta (documento) en un objeto, que contiene información transversal adicional, como esta:

{
   data: { /* your document goes here */ },
   parent: {"abc": 1 },
   children: [ { "boo": 4 }, { "hey": 5} ]
}

siempre que espere que los usuarios no creen demasiados documentos en un solo nivel, puede incluir una lista de niños en la respuesta. Si ese no es el caso, podría ofrecerle al usuario que recupere las identificaciones de documentos secundarios de esta manera, permitiendo, por ejemplo, paginar los resultados a través de parámetros de cadena de consulta:

GET /rest/documents/2/children?page=2&size=50

Finalmente, hablando de los parámetros de la cadena de consulta, también puede proporcionar la información de ruta directamente a través de los parámetros de la cadena de consulta:

GET /rest/documents?path=somepath&page=1&size=42

Todos los enfoques mencionados esperan que el plano GET /rest/documentsdevuelva solo documentos raíz.

— netchkin
fuente

Buena idea. Sin embargo, la relación con los documentos secundarios no está clara en la API si los documentos secundarios se incluyen en la respuesta para un documento. Si los documentos también tienen otro subrecurso, por ejemplo, comentarios, normalmente accedería a las preguntas de un documento utilizando / documents / {id} / question. Para ser coherente y dejar clara la relación con los documentos secundarios en la API, sugeriría que / documentos / {id} / documentos secundarios accedieran a los documentos secundarios. Las representaciones devueltas serían Documentos al igual que / documents / {id}. Entonces, el resto de lo que describiste aquí todavía funciona también.

— Nathan Ward,

Algo como esto quizás:

/rest/{rootEntity}/Item/{leafEntity}/{id}
/rest/{entity}/ItemList
/rest/{entity}/ItemList/{leafEntity}

donde {rootEntity} es el punto de partida de su colección, {leafEntity} es cualquier nodo hoja con nombre dentro de su árbol.

Puede agregar algunos parámetros a cualquiera de los anteriores para seleccionar, por ejemplo, Último o Todo o algo así.

— Gary Rowe
fuente