REST API design for a large mongo document

Question

I'm having a large document (stored in a Mongo db) and i should expose this document as a REST API. By large I mean more then 200 fields with nested documents and nested list of documents. My question is simple, what is the best approach to design a REST api for such document.

I see 2 options :

1/ Design a single endpoint for the document

[GET] /api/documents ==> will return an array with 1 doc ...

[GET] /api/documents/:id ==> will return the document by it's id

2/ design multiple endpoints for the document

[GET] /api/documents ==> returning all the first level details of the document

[GET] /api/documents/id/field1 ==> returning all inner doc (array of object) from field1 of the document

[GET] /api/documents/id/field1/nid ==> returning object nid from field1 of the document

The application which will consume the REST api will read and modify the data.

This question may seems tedious but for me this is fundamental to the good design of the application which will consume these REST services.

Thanks in advance for your help.

Answer 1

I would suggest going with your first approach, with the addition of a query parameter "depth". The parameter would indicate how many levels deep to fill in the document that's being returned. It can default to 1 or ALL, depending on your clients' needs.

GET /api/documents/342?depth=8
GET /api/documents/78?depth=ALL

That gives them the flexibility to pull as much information as they need without slamming them with the whole document subtree when they just need one node.

It would also be a standard practice for /documents to always return a collection of documents, not a single document. You could use a query parameter to find the root documents:

GET /api/documents?root=true

and then use the id of the root document to pull down however much you need from /api/documents/{id} .