From 7e506ee9826bb3dc270719f22f6d556e63ab2fcf Mon Sep 17 00:00:00 2001 From: "Alexander \"Arav\" Andreev" 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