justcaptcha/README.md

justcaptcha ver. 2.0.0

A simple CAPTCHA service implementation.

Usage

justcaptchad -expiry 5m -listen /var/run/justcaptcha/c.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.

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 implemented by used 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
• 404 if doesn't exist

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. 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 or leaving a page.

HTTP codes

• 204 if solved
• 403 if not solved
• 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