Requirements

A correctly setup cache is required, as the CAPTCHA keys are stored in the cache instead of the database. Django REST CAPTCHA Validator installs all other depedencies on it’s own.

Intallation

Install via pip:

$ pip install -e git+https://github.com/Tsuribori/django_rest_captcha_validator.git#egg=rest_validator

Add rest_validator and Django Simple Captcha to your INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    'captcha',
    'rest_validator',
    ...
]

Remember to migrate:

$ python manage.py migrate

Add entries to your urls.py:

urlpatterns = [
    ...
    path('captcha/', include('captcha.urls')),
    path('validate/', include('rest_validator.urls')),
    ...
]

Usage

Django REST CAPTCHA Validator provides a RestCaptchaField that can be added to a serializer:

from rest_validator.fields import RestCaptchaField
from rest_framework import serializers
from .models import Item

class ItemSerializer(serializers.ModelSerializer):

    captcha_key = RestCaptchaField()

    class Meta:
        model = Item
        fields = ('item_text', 'captcha_key')

    def create(self, validated_data):
        validated_data.pop('captcha_key')
        instance = super().create(validated_data)
        return instance

The field is used in validating human input. It’s important that the “create” method of a ModelSerializer is overridden to delete the “captcha_key” from the “validated_data” dictionary, as otherwise a TypeError occurs due to “captcha_key” not being a field on the model.

The package also provides a RestCaptchaView that is mapped to the URL given to it, in this case /validate/. A GET request to the view will generate a new CAPTCHA challenge, and return a CAPTCHA key value and an URL to the challenge image, for example:

{
    "captcha_key": "e0411286a3c3f5b57d859747eb8811d3bd023b3a",
    "captcha_image": "http://localhost:8000/captcha/image/e0411286a3c3f5b57d859747eb8811d3bd023b3a/"
}

A POST request to the view will accept “captcha_key” and “captcha_value” fields. The value of “captcha_value” must be the value of the solved CAPTCHA that “captcha_key” points to. On a succesful POST request with valid data the following is returned:

{
    "validated": true
}

A request with an expired “captcha_key” or invalid “captcha_value” will return:

{
    "non_field_errors: [
        "Invalid or expired CAPTCHA"
    ]
}

After a CAPTCHA is succesfully validated, the “captcha_key” of the CAPTCHA in question can be used in a serializer with a RestCaptchaField to validate human input. If a “captcha_key” that is expired or not validated is used in a serializer, the following error occurs during serializer validation:

{
    "captcha_key": [
        "Invalid or expired CAPTCHA"
    ]
}

Settings

There is currently two settings associated with Django REST CAPTCHA Validator. The first is REST_VALIDATOR_CACHE_TIMEOUT. This setting, in seconds, controls how long a validated CAPTCHA persists in the cache. The default is 300 seconds. REST_VALIDATOR_SINGLE_USE controls is a validated “captcha_key” valid for only a single use or as long as the validated value exists in the cache, i.e. the duration of REST_VALIDATOR_CACHE_TIMEOUT. The default is True.

All other CAPTCHA settings are controlled by settings associated with Django Simple Captcha. List of those can be viewed in their documentation.