1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
# HTTP API Referrence
## Notations used in this page
- `*` means a parameter is optional, otherwise it's required.
- `<xxx>` means it's an variable, which will be replaced in the actual response.
- `<config:xxx>` means it's from user's configuration.
- `<value1 | value2 | value3>` means it will be replaced with one of the values.
- `{xxx}` means it's an input, which needs to be replaced with actual value in requests.
---
## Receiver endpoint
Receiver endpoint is where people send their webmentions to. It's a route that accepts POST request with form parameters `source` and `target`.
| Method | Path |
| ------ | ----------------------------------------------------- |
| `POST` | `/endpoint` (can be configured using option `:endpoint`, see `config.edn`) |
| Post Params | Description | Default |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `source` | Where webmention is coming from. The page that mentioned `target`. | None |
| `target` | Where webmention is sent to. The page that was mentioned by `source`. Target's domain should be in the allow list of receiver. (allow list is `:allowed-target-domains` in `config.edn`) | None |
The endpoint responds with status code `201` and a `Location` header pointing to the webmention. It'll take some time for weepinbell to verify, process and store webmention. Senders should check the `Location` URL a few minutes after.
An immediate response is made upon request:
```json
{
"status": "201",
"message": "Webmention is accepted and pending for verification.",
"url": "<config:base_url>/api/mention/<webmention_id>"
}
```
The receiver does basic checks. If there's something wrong, it reponds with status code `400` and returns a JSON body:
```json
{
"status": "400",
"message": "<specifc_error_message>"
}
```
All possible messages and their meanings:
- "Invalid URLs. Source and target have to be valid http(s) urls."
- "Source and target are identical."
- "Domain of target is not allowed. This receiver does not receive webmention on its behalf."
The message themselves should be informative enough.
---
## Query routes
### Querying a specific webmention
| Method | Path |
| ------ | ----------------------------------------------- |
| `GET` | `/api/mention/{id}` |
| `GET` | `/api/mention/?source={source}&target={target}` |
An example response:
```json
{
"webmention": {
"source": "<source>",
"target": "<target>",
"id": "<32_digit_SHA_256_hash>",
"modified": <timestamp_of_last_modified>
},
"jf2": {
"type": "entry", // it's always "entry"
"name": "Title of this entry",
"url": "URL to this entry",
"author": {
"type": "card", // it's always "card"
"name": "Name of author",
"url": "URL to this author",
"photo": "Photo URL" // optional
},
"published": "Date string of published date",
"content": {
"html": "<p>content of this entry</p>",
"text": "content of this entry"
},
"summary": "Summary or description of this entry", // optional
"wm-property": "mention", // or "like-of", "repost-of", "in-reply-to", "rsvp"
// below are fields that only exists when the coresponding "wm-property" is present
"like-of": "URL that this webmention represents a like of",
"repost-of": "URL that this webmention represents a repost of",
"in-reply-to": "URL that this webmention replies to",
"rsvp": "URL to the event that this webmention represents an RSVP for"
},
"extra": {
"proxied-photo": "<config:base_url>/avatars/<photo_path>"
}
}
```
### Querying a list of webmentions
| Method | Path | Description |
| ------ | ----------------------------- | -------------------------------------- |
| `GET` | `/api/mentions/{domain}` | Webmentions sent to a specific domain. |
| `GET` | `/api/mentions/?url={target}` | Webmentions sent to a specific URL. |
| Query Params | Description | Default |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `page`* | Page number starting from `0`. **If no page number, weepinbell returns a full list.** If not a number (e.g. `last`, a string), weepinbell returns the last page. | None |
| `jf2type`* | Filters webmentions by their JF2 type (.i.e the `wm-property`). Available types are `like-of`, `repost-of`, `in-reply-to` and `rsvp`. If absent, no filter is applied. | None |
The responses are mostly the same as `/api/mention/{id}` except that there are multiple webmention items wrapped inside a JSON array.
### Couting a list of webmentions
| Method | Path | Description |
| ------ | -------------------------- | ----------------------------------------------- |
| `GET` | `/api/count/{domain}` | Count of webmentions sent to a specific domain. |
| `GET` | `/api/count/?url={target}` | Count of webmentions sent to a specific URL. |
An example response:
```json
{
"count": "<integer>"
}
```
### Sending webmentions
| Method | Path | Description |
| ------ | -------------------------- | ----------------------------------------------- |
| `POST` | `/api/send/` | Count of webmentions sent to a specific domain. |
| Post Params | Description | Default |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `source` | Where webmention is coming from. The page that mentioned `target`. | None |
| `target` | Where webmention is sent to. The page that was mentioned by `source`. Target's domain should be in the allow list of receiver. (see [configuration](./configuration.md)) | None |
Currently implemented as an alias of `/endpoint`.
Will support sending webmentions to other servers in the future. See issue [#24](https://codeberg.org/eltrac/weepinbell/issues/24).
|
