98 lines
2.5 KiB
Markdown
98 lines
2.5 KiB
Markdown
justcaptcha ver. 2.0.0
|
|
======================
|
|
|
|
A simple CAPTCHA service implementation.
|
|
|
|
## Service usage
|
|
|
|
justcaptchad -expiry 10m -listen /var/run/justcaptcha/sock
|
|
|
|
`-expiry` takes time for CAPTCHA to be valid for in format X{s,m,h}.
|
|
|
|
`-listen` is `ip:port` or `/path/to/unix.sock` to listen on.
|
|
|
|
## Service HTTP API
|
|
|
|
### Errors
|
|
|
|
All error codes are returned with an error message in `text/plain`.
|
|
|
|
### Create a new CAPTCHA
|
|
|
|
POST /
|
|
|
|
It will return an ID of a new CAPTCHA in `text/plain`.
|
|
|
|
#### HTTP codes
|
|
- `201` if created (always being created)
|
|
|
|
### Get an image for a CAPTCHA
|
|
|
|
GET /:captcha_id/image?style=
|
|
|
|
Responds with an image in JPEG format (`image/jpeg`).
|
|
|
|
An optional URL parameter `style=` set a name of a CAPTCHA style if it is
|
|
supported by CAPTCHA implementation.
|
|
|
|
#### HTTP codes
|
|
- `200` if exists
|
|
- `404` if doesn't exist
|
|
- `500` if for some reason an image wasn't created
|
|
|
|
### Submit an answer
|
|
|
|
POST /:captcha_id
|
|
|
|
Accepts `application/x-www-form-urlencoded` content type.
|
|
|
|
It takes one parameter `answer=123456`.
|
|
|
|
Responds with an empty body and one of the HTTP codes.
|
|
|
|
#### HTTP codes
|
|
- `202` if solved
|
|
- `403` if not solved
|
|
|
|
### Check if captcha is solved
|
|
|
|
GET /:captcha_id?remove
|
|
|
|
Responds with an empty body and one of the HTTP codes.
|
|
|
|
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.
|
|
|
|
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 or leaving a page.
|
|
|
|
#### HTTP codes
|
|
- `204` if solved
|
|
- `403` if not solved
|
|
|
|
### 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 |