Hypermedia URLS

Hypermedia URLs

These URLs are used to address content in the Hypermedia protocol. The URL generally follows the format: hm://[ACCOUNT_ID]/[PATH]?[PARAMETERS]

Protocol

Hypermedia URLs are always prefixed with the hm:// protocol, so they may be distinguished from other URL types such as https:// and ipfs://

Account

The first term of the Hypermedia URL is the only required part: an Account ID.

A basic Hypermedia URL is hm://z6MkjPVNrNGA6dYEqkspBvfuTnAddw7hrNc5WM6dQDyuKkY3 which refers to the Home Document of this Account.

Path

If the path is missing, the URL will refer to the Home Document of that account.

Parameters

Optional query parameters to be specified after the ? part of the hypermedia URL.

v - Version

l - Latest

Latest

When this ?l is specified, the reader will attempt to load the most recent version of the document.

Version

Specifies the version of the document to load. The version is defined as a list of Change CIDs, where the CIDs may be concatenated with a . character if there is more than one.

If the latest query param is included, the `?v=[VERSION]` param specifies the lowest allowed version of the document. The URL would be specifying that it wants this version at least, but would prefer the latest.

If the version is specified without the ?l param, the URL points to this exact version of a the document.

Web URLs

A HTTPS URL may also resolve to a Hypermedia site or document. There are two types of web URLs that can be converted to full Hypermedia URLs.

Short Links

The content of a Hypermedia site may be published directly onto a domain.

If Alice has published to the domain alice.me, content in her account will be directly addressible from the domain's paths. So her document that is usually addressed through hm://<Alice Account ID>/sushi can be accessed through https://alice.me/sushi

If you're looking at an arbitrary web URL like https://example.com/foo/bar, you need to know if example.com is a published hypermedia site, and if so, what is the account ID that corresponds to the Hypermedia URL. This is currently determined by looking up the JSON at https://example.com/hm/api/config to see what the Account ID is. Although, this may change in the future (for example a DNS lookup may eventually be supported).

Also the current implementation provides HTML metadata to specify the Hypermedia URL. For example, this page (located at https://hyper.media/protocol/links/hm-urls) includes the following metadata:

<meta name="hypermedia_id" content="hm://z6MkfzKMhF9k1oPaQsShWAg8xJzbWf5kaZgn1MkeZvhcAsmB/protocol/links/hm-urls" />
<meta name="hypermedia_version" content="bafy2bzacea3wzhzlpny4zivh44rp3o2nvmt3u4qoazmveofxmzg2wv7zwii7k" />

HTTPS link with Hypermedia Account

When content is published on a web gateway or when it is being served from a different site, the path will be prefixed with /hm and will have the following format:

https://<Domain>/hm/<Account ID>/<Path>?<Parameters>

If you see a URL like this, you can convert it directly into a Hypermedia URL, as long as you know that the domain is running Hypermedia software. It converts into:

hm://<Account ID>/<Path>?<Parameters>

So if you have a domain that is already known to be a Hypermedia domain, such as https://hyper.media, you can immediately convert such URLs into HM URLs for use on the peer-to-peer network. So even if the centralized hyper.media server goes down, you can continue to use https://hyper.media/hm/ URLs as if they are hm:// URLs

Discussions