justcaptcha/README.md

justcaptcha ver. 1.1.2
======================

A simple CAPTCHA service implementation.

## Usage

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

### Get a new CAPTCHA

    GET /

It will return an ID of a new CAPTCHA in plain text.

#### HTTP codes
- `200` if created (and it always being created)

### Get an image for a CAPTCHA

    GET /:captcha_id/image?style=

Responds with an image in JPEG format.

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 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
- `200` 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` 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
- `403` if not solved
- `404` if doesn't exist