11

Posting a bug report on Stack Apps, I tried to link to its API docs:

http://api.stackoverflow.com/1.0/help/method?method=posts/{id}/comments

It was unsuccessful, and making the link explicit with [http://url.com][1] doesn't work either because the link doesn't show up. E.g., this is supposed to be a link.

17

RFC 1738 states that certain characters are unsafe in URLs:

Unsafe:

Characters can be unsafe for a number of reasons. [...] Other characters are unsafe because
gateways and other transport agents are known to sometimes modify such characters. These characters are "{", "}", "|", "\", "^", "~", "[", "]", and "`".

All unsafe characters must always be encoded within a URL. For example, the character "#" must be encoded within URLs even in systems that do not normally deal with fragment or anchor identifiers, so that if the URL is copied into another system that does use them, it will not be necessary to change the URL encoding.

The { symbol should be replaced with %7B and } with %7D.

For example: http://api.stackoverflow.com/1.0/help/method?method=posts/%7Bid%7D/comments

  • I would aks why they're not encoded on SO, but still that makes sense. Thanks. – Nikita Rybak Feb 12 '11 at 12:07
1

It looks like those links are working now, but they should not. Using the new API endpoint to demonstrate:

https://api.stackexchange.com/2.2/comments/{ids}?site=stackoverflow

This is not a URI. As mentioned previously, curly braces are unsafe characters, and are not valid in URIs (see RFC 3986). For the purposes of API documentation, and other similar uses, they should not be percent encoded, however, because they still aren't URIs - they don't identify a resource. When the embedded parameter expression is expanded, in this case by replacing it with a semicolon delimited list of ids, they do identify a resource. As such, it's a valid URI.

https://api.stackexchange.com/2.2/comments/1;2?site=stackoverflow

Using curly braces to indicate an embedded parameter in a URI-like descriptor - called a URI template - is defined by RFC 6570.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .