Browse Source

Add docstring to webmention:status endpoint

Danielle McLean 8 months ago
parent
commit
e5bad72e36
Signed by: Danielle McLean <dani@00dani.me> GPG Key ID: 8EB789DDF3ABD240
1 changed files with 20 additions and 1 deletions
  1. 20
    1
      webmention/views.py

+ 20
- 1
webmention/views.py View File

@@ -62,6 +62,25 @@ def accept(request):
62 62
 
63 63
 
64 64
 @require_GET
65
-def status(request, mention_id):
65
+def status(mention_id):
66
+    """
67
+    Retrieve the verification status of the specified webmention.
68
+
69
+    A webmention is accepted synchronously by the target site (me, in this
70
+    case) and then must be verified asynchronously - this means contacting the
71
+    source URL and confirming that it really does link to the target URL it
72
+    claimed to. Until this verification is complete, we can't assume the
73
+    mention is real and shouldn't display it anywhere.
74
+
75
+    Therefore, when a webmention is accepted, we return a Location header
76
+    pointing to this endpoint. The source site may, if desired, use this
77
+    endpoint to check whether their webmention has been verified or not.
78
+
79
+    The status is currently returned as a plain string, e.g., 'pending'.
80
+    However, eventually this will use a nice template instead, possibly
81
+    displaying additional information about the mention. There's no
82
+    standardised format for the status response, and most implementations
83
+    currently use a friendly human-readable format, so I'll be doing the same.
84
+    """
66 85
     mention = get_object_or_404(Webmention.objects, pk=mention_id)
67 86
     return HttpResponse(mention.get_state_display())

Loading…
Cancel
Save