Multi-page document as images over REST

Question

I'm attempting to expose a RESTful URL that returns a multi page document. With a PDF it's quite simple in my opinion.

GET /documents/12345.pdf

But I also wish to expose the same document with an image format where each page is a separate jpg. How would I best go about constructing the URL?

So far I'm torn between

GET /documents/12345/page1.jpg

or

GET /documents/12345.jpg?page=1

or

GET /document/12345?page=1&type=jpg

I know there is no absolute right way to do this I'm just looking for what is most intuitive. I've spent so much time looking at this that I can't tell which one I like best or even if there is an alternate approach that would be better.

Thanks!

Answer 1

The Resource

Your resource is the document. The PDF and JPEG are two representations of this resource. So both are available under

/documents/12345

Content Negotiation

How does the client select the PDF or the JPEG? That's what the HTTP header Accept is for.

GET /documents/12345
Accept: image/jpeg

for the JPEG represenation,

GET /documents/12345
Accept: application/pdf

for the PDF represenation.

Pages

Now we still have the problem of pages. Here I would recommend to follow the approach mentioned in the comments:

GET /documents/12345/1
Accept: image/jpeg

for page 1 of the JPEG represenation.

Problems

There still is a small problem: What happens with this request?

GET /documens/12345/1
Accept: application/pdf

Is there 'page 1' of the PDF representation as a separate entity? Perhaps there is, if your RESTful service can generate it.

But we are not finished. What happens with this request?

GET /documents/12345
Accept: image/jpeg

Is there a single-page version of the JPEG representation? Again, perhaps there is, if your RESTful service can generate it. Perhaps it could generate a all-pages-on-one-page JPEG. If it can't, return 404 Not Found.