rest - 多页文档作为 REST 上的图像

Question

我正在尝试公开一个返回多页文档的 RESTful URL。在我看来，使用 PDF 非常简单。

GET /documents/12345.pdf

但我也希望以图像格式公开同一文档，其中每个页面都是一个单独的 jpg。我最好如何构建 URL？

至今我还在纠结

GET /documents/12345/page1.jpg

或

GET /documents/12345.jpg?page=1

或

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

我知道没有绝对正确的方法来做到这一点，我只是在寻找最直观的方法。我花了很多时间研究这个，以至于我无法说出我最喜欢哪一个，或者即使有更好的替代方法也是如此。

谢谢!

Answer 1

资源

您的资源是文档。 PDF 和 JPEG 是此资源的两种表示。所以两者都可用

/documents/12345

内容协商

客户端如何选择PDF或JPEG？这就是HTTP header Accept是为了。

GET /documents/12345
Accept: image/jpeg

对于 JPEG 表示，

GET /documents/12345
Accept: application/pdf

用于 PDF 表示。

页面

现在我们还有页面的问题。在这里我建议遵循评论中提到的方法:

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

对于 JPEG 表示的第 1 页。

问题

还有一个小问题:这个请求会发生什么？

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

是否有作为单独实体的 PDF 表示的“第 1 页”？也许有，如果您的 RESTful 服务可以生成它的话。

但我们还没有完成。这个请求会发生什么？

GET /documents/12345
Accept: image/jpeg

是否有 JPEG 表示的单页版本？同样，如果您的 RESTful 服务可以生成它，也许存在。也许它可以生成一页上所有页面的 JPEG。如果不能，返回 404 Not Found。