README updated.
This commit is contained in:
parent
fa47cfa20e
commit
07c8a90ada
64
README.md
64
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
|
||||
- `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
|
Loading…
Reference in New Issue
Block a user