Multi-page document as images over REST (additional questions)

Question

I read this question - Multi-page document as images over REST which has very nice answer. We have similar scenario but with some additional requirement.

1. The request can either return the document as binary data or upload the pdf/jpeg(s) somewhere and return a URL to the uploaded file. How should the calls be different? What is coming to my mind is to use GET for the binary data response and POST when it uploads and returns URL. When it is POST it will return 201 (Created) and return the URL to the uploaded document.

2. There is also one more detail about the first point. When uploading and returning a URL we can either upload for a temporary usage (and delete it after some time) or make it permanent. Should we do this by adding query parameter? like - POST /documents/12345.pdf?permanent=true

3. As in the original question, we also return different jpeg for every page. But the process of creating the document is time consuming so we want to take all pages at one request. What would be the proper way of doing this? I think in the 201 response you can only return one URL.

4. Is the GET /documents/12345.pdf approach a good alternative of the accept header or there are also other approaches? Would using the slash instead of dot be better, like GET /documents/12345/pdf? This way it wouldn't be needed to parse the "12345.pdf" string.

Thanks!

Answer 1

I've learned a thing or two in the past two years lets see if I can take a stab at this...

1. You can make the POST request always return the URI of the newly created resource. Do you ever need the POST to return the binary if you're the one providing it in the first place? I think I'm tracking with you in this case the GET would return the binary and the POST would create the resource and return the location (URI) of the newly created resource.
2. This isn't RESTful as GETs should be safe (GETs don't modify resources). You could make it a PUT if you want to update the status after the fact or when you POST you could add a flag in the request body to mark it should be permanent. Info on POSTing an image and data can be found here
3. For #3 do you want to fetch or upload everything in one request? You can return whatever you want in the response. You could structure your request in such a way to return a json array of urls. For example if you structure your request similar to my example then GET /documents/12345/1 may return page 1 of document 12345 while GET /documents/12345 may return all pages to document 12345.
4. For #4 I wouldn't do /pdf as that represents resource hierarchy. PDF is only the representation of the document, not the actual document. I would vote querystring since there may be other attributes. For example imagine trying to do the following with slashes... GET /documents/12345?format=pdf&color=grayscale&quality=300dpi&layout=portrait