3

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!

Henke
  • 4,445
  • 3
  • 31
  • 44
Steven
  • 1,670
  • 4
  • 17
  • 26
  • 2
    How about GET /documents/pdf/12345 and GET /documents/jpg/12345/1 ? – tranceporter Oct 19 '12 at 14:02
  • 1
    @tranceporter Post this as an answer and I'll upvote it :) And don't forget to mention the HTTP `Accept` header :) –  Oct 19 '12 at 14:06

2 Answers2

4

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.

  • thanks for pointing out the problems of specifying a pdf page or not specifying a jpg page, I'll be returning a 404 in those scenarios. – Steven Oct 19 '12 at 14:31
  • @user647772 very nice explanation. We have similar scenario but with some additional requirement. I have posted a new question for it - [Multi-page document as images over REST (additional questions)](https://stackoverflow.com/questions/28107711/multi-page-document-as-images-over-rest-additional-questions). I am curious, what you can suggest for our case. – Boris Toninski Jan 23 '15 at 10:25
1

How about 

GET /documents/pdf/12345

and

GET /documents/jpg/12345/1

When using REST, I prefer to expose resources without using parameters or querystring. That way it fits the RESTful syntax, and is easier to parse with the in-built Routing in ASP.NET MVC.

Like @Tichodroma said about Http Headers, it is generally not preferable to use custom HTTP headers when using REST. Have a look here for good explanation:

REST: HTTP headers or request parameters

Community
  • 1
  • 1
tranceporter
  • 2,241
  • 1
  • 21
  • 23