From 7e506ee9826bb3dc270719f22f6d556e63ab2fcf Mon Sep 17 00:00:00 2001
From: "Alexander \"Arav\" Andreev" <me@arav.top>
Date: Sun, 28 Aug 2022 23:33:59 +0400
Subject: [PATCH] A README was rewritten and complemented with a new behavior
 of a GET /:id endpoint.

---
 README.md | 36 ++++++++++++++++++++++++------------
 1 file changed, 24 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index df77369..e31ac7d 100644
--- a/README.md
+++ b/README.md
@@ -13,36 +13,38 @@ A simple CAPTCHA service implementation.
 
 ## API
 
-### Get a new captcha
+### Get a new CAPTCHA
 
     GET /
 
-It will return an ID of a new captcha in plaintext.
+It will return an ID of a new CAPTCHA in plain text.
 
 #### HTTP codes
-- `200` if created
+- `200` if created (and it always being created)
 
-### Get an image for a captcha
+### Get an image for a CAPTCHA
 
     GET /:captcha_id/image?style=
 
-Responds with an image (e.g. in PNG format).
+Responds with an image in JPEG format.
 
-An optional query parameter `style=` could be supplied if captcha implementation
-support different styles.
+An optional URL query parameter `style=` set a name of a CAPTCHA style if
+implemented by used CAPTCHA implementation.
 
 #### HTTP codes
 - `200` if exists
 - `404` if doesn't exist
-- `500` if for some reason Image wasn't created
+- `500` if for some reason an image wasn't created
 
 ### Submit an answer
 
     POST /:captcha_id
 
-It takes one form-data parameter `answer=123456`.
+Accepts `application/x-www-form-urlencoded` content type.
 
-Responds with empty body and one of HTTP codes.
+It takes one parameter `answer=123456`.
+
+Responds with an empty body and one of the HTTP codes.
 
 #### HTTP codes
 - `200` if solved
@@ -51,9 +53,19 @@ Responds with empty body and one of HTTP codes.
 
 ### Check if captcha is solved
 
-    GET /:captcha_id
+    GET /:captcha_id?remove
 
-Responds with empty body and one of 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.
+
+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.
 
 #### HTTP codes
 - `200` if solved