Merge pull request #883 from ix5/api-endpoints-apidoc-docs

[server] Remove obsolete /count GET, apiDoc improvements

CHANGES.rst

@@ -24,8 +24,11 @@ Changelog for Isso
   to style comments and replies made by the page's author(s).
 - Add Ukrainian localisation (`#878`_, okawo80085)
 - Enable Turkish localisation (`#879`_, okawo80085)
-- Add ``/config`` endpoint for fetching server configuration options that
-  affect the client
+- **API:**
+
+  - Add ``/config`` endpoint for fetching server configuration options that
+    affect the client
+  - Remove ``/count`` GET endpoint (use POST instead)
 
 .. _Gravatar: Image requests: http://en.gravatar.com/site/implement/images/
 .. _879: https://github.com/posativ/isso/pull/879

Makefile

@@ -30,7 +30,7 @@ DOCS_CSS_DST := docs/_static/css/site.css
 
 DOCS_HTML_DST := docs/_build/html
 
-APIDOC_SRC := apidoc/apidoc.json apidoc/header.md apidoc/footer.md
+APIDOC_SRC := apidoc/apidoc.json apidoc/header.md apidoc/footer.md apidoc/_apidoc.js
 
 APIDOC_DST := apidoc/_output
 
@@ -79,7 +79,9 @@ apidoc-init:
 
 apidoc: $(ISSO_PY_SRC) $(APIDOC_SRC)
 	$(APIDOC) --config apidoc/apidoc.json \
-		--input isso/views/ --output $(APIDOC_DST)
+		--input isso/views/ --input apidoc/ \
+		--output $(APIDOC_DST)
+	cp -rT $(APIDOC_DST) $(DOCS_HTML_DST)/docs/api/
 
 coverage: $(ISSO_PY_SRC)
 	coverage run --omit='*/tests/*' --source isso -m pytest

apidoc/_apidoc.js

@@ -0,0 +1,69 @@
+// ------------------------------------------------------------------------------------------
+// History.
+// ------------------------------------------------------------------------------------------
+/**
+* @api {get} /count (Deprecated) Count for single thread
+* @apiGroup Thread
+* @apiName count
+* @apiVersion 0.12.6
+* @apiDeprecated use (#Thread:counts) instead.
+* @apiDescription
+*     (Deprecated) Counts the number of comments for a single thread.
+
+* @apiBody {Number[]} urls
+*     Array of URLs for which to fetch comment counts
+
+* @apiExample {curl} Get the respective counts of 5 threads:
+*     curl 'https://comments.example.com/count' -d '["/blog/firstPost.html", "/blog/controversalPost.html", "/blog/howToCode.html", "/blog/boringPost.html", "/blog/isso.html"]
+
+* @apiSuccessExample {json} Counts of 5 threads:
+*     [2, 18, 4, 0, 3]
+*/
+
+/**
+* @api {post} /new create new
+* @apiGroup Comment
+* @apiName new
+* @apiVersion 0.12.6
+* @apiDescription
+*     Creates a new comment. The server issues a cookie per new comment which acts as
+*     an authentication token to modify or delete the comment.
+*     The token is cryptographically signed and expires automatically after 900 seconds (=15min) by default.
+* @apiUse csrf
+
+* @apiQuery {String} uri
+*     The uri of the thread to create the comment on.
+* @apiBody {String{3..}} text
+*     The comment’s raw text.
+* @apiBody {String} [author]
+*     The comment’s author’s name.
+* @apiBody {String} [email]
+*     The comment’s author’s email address.
+* @apiBody {String} [website]
+*     The comment’s author’s website’s url.
+* @apiBody {number} [parent]
+*     The parent comment’s id if the new comment is a response to an existing comment.
+
+* @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
+
+* @apiUse commentResponse
+
+* @apiSuccessExample {json} Success after the above request:
+*     HTTP/1.1 201 CREATED
+*     Set-Cookie: 1=...; Expires=Wed, 18-Dec-2013 12:57:20 GMT; Max-Age=900; Path=/
+*     X-Set-Cookie: isso-1=...; Expires=Wed, 18-Dec-2013 12:57:20 GMT; Max-Age=900; Path=/
+*     {
+*         "website": null,
+*         "author": "Max Rant",
+*         "parent": 15,
+*         "created": 1464940838.254393,
+*         "text": "<p>Stop saying that! <em>isso</em>!</p>",
+*         "dislikes": 0,
+*         "modified": null,
+*         "mode": 1,
+*         "hash": "e644f6ee43c0",
+*         "id": 23,
+*         "likes": 0
+*     }
+*/

apidoc/apidoc.json

@@ -2,8 +2,9 @@
   "name": "Isso API",
   "title": "Isso API",
   "description": "",
-  "version": "0.13.0-dev",
-  "order": ["Thread",  "Comment"],
+  "version": "0.13.0",
+  "order": ["Thread",  "Comment", "Demo", "Admin",
+            "feed", "counts", "count", "config", "fetch"],
   "url" : "https://comments.example.com",
   "header": {
     "title": "Introduction",
@@ -14,7 +15,6 @@
     "filename": "footer.md"
   },
   "template": {
-    "withCompare": false
+    "withCompare": "true"
   }
 }
-

apidoc/footer.md

@@ -1,8 +1,14 @@
 # Help
 
 To generate this documentation:
-```bash
-git clone https://github.com/posativ/isso && cd isso
-make apidoc-init apidoc
-$BROWSER apidoc/_output/index.html
-```
+
+1. Install `Node.js` and `npm`
+2. Run:
+  ```console
+  git clone https://github.com/posativ/isso && cd isso
+  make apidoc-init apidoc
+  ```
+3. View API documentation in browser at `./apidoc/_output/index.html`:
+  ```console
+  xdg-open apidoc/_output/index.html
+  ```

apidoc/header.md

@@ -1,10 +1,29 @@
 # Introduction
 
 This is the API documentation of the Isso commenting system.
+**[Click here](/docs/)** to get back to the regular **Isso documentation**.
+
+### What can you do?
+
+- Fetch comment threads
+- Post, edit and delete comments
+- Get information about the server
+- Like and dislike comments
+- ...and much more!
+
+### Technical details
+
+These API docs are automatically generated by [apiDoc][apidoc] from
+[isso/views/comments.py](https://github.com/posativ/isso/blob/master/isso/views/comments.py).
+
+You can select previous versions from a dropdown on the upper right of the
+page.
 
 For more information about Isso, visit **[posativ.org/isso](https://posativ.org/isso)**
 or check out the source at **[GitHub](https://github.com/posativ/isso)**.
 
+[apiDoc]: https://apidocjs.com/
+
 ### Conventions
 
 This documenation uses `https://comments.example.com` as the base URL for Isso's API.