Home/ Questions/Q 8720427
In Process

The Archive Base Latest Questions

Editorial Team
  • 0
Asked: 2026-06-13T07:02:24+00:00

I’m attempting to expose a RESTful URL that returns a multi page document. With

  • 0

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!

Share

Leave an answer

You must login to add an answer.

Need An Account,

1 Answer

  1. Editorial Team

    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.

    • 0