views: comments: Document title parameter and improve error handling for /new API

- Update API documentation to include optional title parameter for new comments.
- Change error handling: when creating the first comment for a new thread, return a BadRequest if the URI is inaccessible and no title is provided, prompting the user to supply a title.

Fixes #1055

Author: pkvach

CHANGES.rst

@@ -56,6 +56,7 @@ Bugfixes & Improvements
 - Make 'text' field in 'comments' table NOT NULL and handling data migration (`#1019`_, pkvach)
 - Python 3.12 support (`#1015`_, ix5)
 - Disable Postbox submit button on click, enable after response (`#993`_, pkvach)
+- Document title parameter and improve error handling for /new API (`#1058`_, pkvach)
 
 .. _#951: https://github.com/posativ/isso/pull/951
 .. _#967: https://github.com/posativ/isso/pull/967
@@ -70,6 +71,7 @@ Bugfixes & Improvements
 .. _#1019: https://github.com/isso-comments/isso/pull/1019
 .. _#1015: https://github.com/isso-comments/isso/pull/1015
 .. _#993: https://github.com/isso-comments/isso/pull/993
+.. _#1058: https://github.com/isso-comments/isso/pull/1058
 
 0.13.1.dev0 (2023-02-05)
 ------------------------

isso/views/comments.py

@@ -293,6 +293,8 @@ def verify(cls, comment):
         The comment’s author’s website’s url. Must be Django-conform, i.e. either `http(s)://example.com/foo` or `example.com/`
     @apiBody {Number} [parent]
         The parent comment’s id if the new comment is a response to an existing comment.
+    @apiBody {String} [title]
+        The title of the thread. Required when creating the first comment for a new thread if the title cannot be automatically fetched from the URI.
 
     @apiExample {curl} Create a reply to comment with id 15:
         curl 'https://comments.example.com/new?uri=/thread/' -d '{"text": "Stop saying that! *isso*!", "author": "Max Rant", "email": "rant@example.com", "parent": 15}' -H 'Content-Type: application/json' -c cookie.txt
@@ -350,7 +352,7 @@ def new(self, environ, request, uri):
                         if resp and resp.status == 200:
                             uri, title = parse.thread(resp.read(), id=uri)
                         else:
-                            return NotFound(f'URI {uri} does not exist')
+                            return BadRequest(f'Cannot create new thread: URI {uri} is not accessible and no title was provided. Please provide a title parameter in your request.')
                 else:
                     title = data['title']