Hypermedia Comment URLs

Problem

We need a URL format for comments so that they can be addressed from documents, comments, and so you can follow a URL to open them on the web or in the app

Solution

Option A. hm://c/COMMENT_ID?target=SITE_ID/path/to/doc

This works in many cases but doesn't include the target doc ID, which may introduce some performance issues

Option B. hm://SITE_ID/path/to/doc?comment=COMMENT_ID

This is ugly and a query param is not the ideal way to reference another entity. If there are more query params, do they affect the document or the comment?

Option C. hm://SITE_ID/path/to/doc/_comment_COMMENT_ID

This is nice because it includes the doc ID, and its clear that it references a comment

We could also use -comment-COMMENT_ID as the delimiter, or use .comment, if we prefer

This implies that the user should be prohibited from starting document pathnames with _, as it is a reserved namespace for us. This allows more flexibility in the future.

Scope

Very easy to copy comment URLs. A bit more work to make them explicitly openable as it requires support on web and the app. Even more work for comment embeds. With 100% focus this is possible with 1 week of front-end dev.

Backend support: include comments and their target documents as reference materials when they are linked or embedded from another doc or comment

Activity