From 07c8a90ada070b07502f704491ff9ce5c5a827a6 Mon Sep 17 00:00:00 2001
From: "Alexander \"Arav\" Andreev" <me@arav.top>
Date: Thu, 20 Oct 2022 22:49:08 +0400
Subject: [PATCH] README updated.

---
 README.md | 64 +++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 46 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 4f94ce3..30f2fe8 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,11 @@
-justcaptcha ver. 1.2.0
+justcaptcha ver. 2.0.0
 ======================
 
 A simple CAPTCHA service implementation.
 
 ## Usage
 
-    justcaptchad -expiry 5m -listen /var/run/justcaptchad/j.sock
+    justcaptchad -expiry 5m -listen /var/run/justcaptcha/c.sock
 
 `-expiry` takes time for CAPTCHA to be valid for in format X{s,m,h}.
 
@@ -13,22 +13,26 @@ A simple CAPTCHA service implementation.
 
 ## API
 
-### Get a new CAPTCHA
+### Errors
 
-    GET /
+All error codes are returned with an error message in `text/plain`.
 
-It will return an ID of a new CAPTCHA in plain text.
+### Create a new CAPTCHA
+
+    POST /
+
+It will return an ID of a new CAPTCHA in `text/plain`.
 
 #### HTTP codes
-- `200` if created (and it always being created)
+- `201` if created (always being created)
 
 ### Get an image for a CAPTCHA
 
     GET /:captcha_id/image?style=
 
-Responds with an image in JPEG format.
+Responds with an image in JPEG format (`image/jpeg`).
 
-An optional URL query parameter `style=` set a name of a CAPTCHA style if
+An optional URL parameter `style=` set a name of a CAPTCHA style if it is
 implemented by used CAPTCHA implementation.
 
 #### HTTP codes
@@ -47,7 +51,7 @@ It takes one parameter `answer=123456`.
 Responds with an empty body and one of the HTTP codes.
 
 #### HTTP codes
-- `200` if solved
+- `202` if solved
 - `403` if not solved
 - `404` if doesn't exist
 
@@ -57,17 +61,41 @@ Responds with an empty body and one of the HTTP codes.
 
 Responds with an empty body and one of the HTTP codes.
 
-If an optional `remove` URL query parameter without a value supplied. CAPTCHA
-will be removed without check if it is solved and a HTTP code `200` will be sent.
-Otherwise, a `403` HTTP code will be sent, and, e.g. browser will print an error
-message to console. So, in this case it helps to keep a browser's console cleaner.
-If CAPTCHA doesn't exist a `404` HTTP code still will be returned.
+If an optional `remove` parameter without a value supplied CAPTCHA will be
+removed without checking and a HTTP code `204` will be sent. Otherwise, a `403`
+HTTP code will be sent if it is not solved. If a CAPTCHA doesn't exist a `404`
+HTTP code still will be returned.
+
+A `remove` parameter was added because browsers will print an error in a console
+if HTTP code is not within `2xx`, so to keep a console clean you can provide
+this parameter.
 
 This can be useful to remove an unused CAPTCHA from a DB without waiting for it
-to be expired. E.g. when a visitor requests for a new CAPTCHA because he struggle
-to solve it.
+to be expired. E.g. when a visitor requests for a new CAPTCHA or leaving a page.
 
 #### HTTP codes
-- `200` if solved
+- `204` if solved
 - `403` if not solved
-- `404` if doesn't exist
\ No newline at end of file
+- `404` if doesn't exist
+
+### Example of interaction
+
+First a client makes a POST request with empty body to create a new CAPTCHA and obtains an ID for it.
+
+    POST /
+
+As a result we get an ID `n60f2K9JiD5c4qX9MYe90A54nT0nnJrtgfhAjfaWtBg`.
+
+Then a client requests an image for a new CAPTCHA. E.g. with a dark style.
+
+    GET /n60f2K9JiD5c4qX9MYe90A54nT0nnJrtgfhAjfaWtBg/image?style=dark
+
+Then a client submits an answer for a CAPTCHA.
+
+    POST 'answer=198807' /n60f2K9JiD5c4qX9MYe90A54nT0nnJrtgfhAjfaWtBg
+
+And if answer was correct a client gets a HTTP code 202. Or 403 otherwise.
+
+Then a server checks if CAPTCHA was solved with following request.
+
+    GET /n60f2K9JiD5c4qX9MYe90A54nT0nnJrtgfhAjfaWtBg
\ No newline at end of file