Brainstorming Webmention post discovery

This post is a brainstorm and a call for discussion. As discussion advances, I may publish more blog posts on this topic. If I write more on this topic, I will add links to my writings at the beginning of this post for reference.

I am working on a tool called webmemex.js that lets you see information about the incoming and outgoing links on a web page. I have developed a HTML component that retrieves Webmentions from any endpoint that supports the (non-standard) format returned by webmention.io, a popular Webmention server. The component uses the following syntax:

<incoming-links data-api-url="https://webmention.io/..."></incoming-links>

If your site uses webmention.io (or another Webmention endpoint that returns information in the same format), this component will display your Webmentions in a left side panel. Here is an example of the component working on a web page on my site:

The "Incoming Links" sidebar displays Webmentions received by a web page.

While this approach technically works, it requires:

1. The developer to explicitly specify a data URL, and;
2. Only works with webmention.io and sites that return lists of Webmentions in the same format.

This is not ideal, but can be improved. I would like there to be a discovery mechanism that lets a website discover a URL at which they can query Webmentions for a page.

Suppose I have a site, example.com. This site has a Webmention receiver. This site could have an endpoint that, given a URL, returns a list of Webmentions received by the provided URL. To query the URL, I would use:

GET https://example.com/?url=[url]

Where [url] is the URL whose received Webmentions I want to retrieve. This server MUST return jf2 serialized data. Here is an example:

{ "type": "feed", "name": "Webmentions", "children": [ { "type": "entry", "author": { "type": "card", "name": "Tantek Çelik", "photo": "https://tantek.com/logo.jpg", "url": "https://tantek.com/" }, "url": "https://tantek.com/2023/114/t1/venues-reviews-personal-pages", "published": "2023-04-24T13:34:00-07:00", "wm-received": "2023-04-24T22:28:08Z", "wm-id": 1666314, "wm-source": "https://tantek.com/2023/114/t1/venues-reviews-personal-pages", "wm-target": "https://jamesg.blog", "content": { "html": "[omitted for brevity]" }, "mention-of": "https://jamesg.blog", "wm-property": "mention-of", "wm-private": false }, }

This is the same format webmention.io uses right now. It contains all the data one would need to represent a link preview. No need to reinvent the wheel on the structure, but I propose this to be standard: an endpoint that returns jf2-formatted Webmentions received from a URL. This endpoint MUST accept a ?url= parameter.

It is up to the client to define what to return here. An additional parameter MAY be specified to indicate post type:

&post-type=[in-reply-to, like-of, ...]

Suppose example.com supports this mechanism. We now have another problem: how would a website know where to query? Here, we need a discovery mechanism. One approach would be to have a standard <link> header that tells you where to send your webmention data discovery query. This would be specified in addition to the standard webmention header:

<link rel="webmention" href="https://example.com/webmention/endpoint" /> <link rel="webmention-query" href="https://example.com/webmention/retrieve" />

This header could also be specified as a HTTP Link header.

Now, a consumer can:

1. Look for the webmention-query HTTP header or Webmention header, and;
2. Make a standard request to retrieve jf2 for Webmentions that can be manipulated.

If implemented by Webmention servers, I could retrieve Webmentions in a standard way knowing that servers are following a standard format for information retrieval. My extension could also do this discovery entirely automatically, without having to ask a developer to specify an additional data query URL.

Also posted on IndieNews.