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.

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.