如何使用URI作为REST资源？

Question

I am building a RESTful API for retrieving and storing comments in threads.

A comment thread is identified by an arbitrary URI -- usually this is the URL of the web page where the comment thread is related to. This design is very similar to what Disqus uses with their system.

This way, on every web page, querying the related comment thread doesn't require storing any additional data at the client -- all that is needed is the canonical URL to the page in question.

My current implementation attempts to make an URI work as a resource by encoding the URI as a string as follows:

/comments/https%3A%2F%2Fexample.org%2Ffoo%2F2345%3Ffoo%3Dbar%26baz%3Dxyz

However, before dispatching it to my application, the request URI always gets decoded by my server to

/comments/https://example.org/foo/2345?foo=bar&baz=xyz

This isn't working because the decoded resource name now has path delimiters and a query string in it causing routing in my API to get confused (my routing configuration assumes the request path contains /comments/ followed by a string).

I could double-encode them or using some other encoding scheme than URI encode, but then that would add complexity to the clients, which I'm trying to avoid.

I have two specific questions:

1. Is my URI design something I should continue working with or is there a better (best?) practice for doing what I'm trying to do?

2. I'm serving API requests with a Go process implemented using Martini 'microframework'. Is there something Go or Martini specific that I should do to make the URI-encoded resource names to stay encoded? Perhaps a way to hint to the routing subsystem that the resource name is not just a string but a URL-encoded string?

Answer 1

I don't know about your url scheme for your application, but single % encoded values are valid in a url in place of the chars they represent, and should be decoded by the server, what you are seeing is what I would expect. If you need to pass url reserved characters as a value and not have them decoded as part of the url, you will need to double % encode them. It's a fairly common practice, the complexity added to the client & server will not be that much, and a short comment will do rightly.

In short, If you need to pass url chars, double % encode them, it's fine.