Which is the best approach for picking a resource to download a file with a RestApi?

Question

I need to download a file, but, I am wondering which is the best approach to publish my resource. Lets say I have a Document

http://api/documents/id

where I make a GET request should I receive the information of the document with that id including an extra field with the string representation of the file in BASE64? or should I publish another url resource like

http://api/documents/id/download

just for getting the file? The first I know how to do it, but I don't know if that is the proper way. With the later I need advice.

Elusive

Answer 1

On my understanding your document resource consists of both metadata and the actual content of the document. So you could support the following:

• GET /documents/:id: Return a representation of the metadata of the document
• GET /documents/:id/content: Return a representation of the content of the document

---

Alternatively you could support a single endpoint such as GET /documents/:id and return both metadata and content in a multipart response.

---

Content negotiation would be the best approach though. You could use a single endpoint such as GET /documents/:id and Accept: application/json for the metadata and, for example, Accept: application/octet-stream for the content.

Houseroom

What about passing on the header an Accept where based of what you post you receive the file or not? for example, if you send a get with Accept : application/json, it means that the client will get the resource via json. Can you add a specific type for that on the accept? like Accept: application/file? – Elusive

I think Accept header is used for different representations of the same response i.e. JSON vs XML. Seems like a pretty unusual way to differentiate content vs metadata. – Fulvi

Answer 2

how about

GET /documents/:id for metadata
GET /documents/:id?action=download for content

Willmert