justcaptcha/README.md

justcaptcha ver. 2.0.1

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

Library usage

A simple example using built-in dwelling CAPTCHA implementation.

Create a new CAPTCHA:

c := dwcaptcha.NewDwellingCaptcha(expiry)
_, id := inmemdb.New(someAdditionalDataUsedInIDGenerationUsuallyIPAddr, c)

Get an image for a CAPTCHA:

i := inmemdb.Image(captchaID, captchaStyle)
if i == nil {
    ... // error handling
}

jpeg.Encode(w, *i, &jpeg.Options{Quality: 20})

Solve a CAPTCHA:

if ok := inmemdb.Solve(captchaID, answer); !ok {
    ... // not solved
}
// solved
...

Check is CAPTCHA was solved:

if ok := inmemdb.IsSolved(captchaID); !ok {
    ... // not solved
}
// solved
...