From e5bad72e36220f60959a12fe50db2f25d426e734 Mon Sep 17 00:00:00 2001 From: Danielle McLean Date: Fri, 4 May 2018 13:50:50 +1000 Subject: [PATCH] Add docstring to webmention:status endpoint --- webmention/views.py | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/webmention/views.py b/webmention/views.py index 9d02e98..5abd688 100644 --- a/webmention/views.py +++ b/webmention/views.py @@ -62,6 +62,25 @@ def accept(request): @require_GET -def status(request, mention_id): +def status(mention_id): + """ + Retrieve the verification status of the specified webmention. + + A webmention is accepted synchronously by the target site (me, in this + case) and then must be verified asynchronously - this means contacting the + source URL and confirming that it really does link to the target URL it + claimed to. Until this verification is complete, we can't assume the + mention is real and shouldn't display it anywhere. + + Therefore, when a webmention is accepted, we return a Location header + pointing to this endpoint. The source site may, if desired, use this + endpoint to check whether their webmention has been verified or not. + + The status is currently returned as a plain string, e.g., 'pending'. + However, eventually this will use a nice template instead, possibly + displaying additional information about the mention. There's no + standardised format for the status response, and most implementations + currently use a friendly human-readable format, so I'll be doing the same. + """ mention = get_object_or_404(Webmention.objects, pk=mention_id) return HttpResponse(mention.get_state_display())