captcha-rest-validator 0.1
Django Plugin for validating the CAPTCHA
License: MIT License

=============================
Django REST CAPTCHA Validator
=============================

.. image:: https://travis-ci.com/Tsuribori/django_rest_captcha_validator.svg?branch=master
    :target: https://travis-ci.com/Tsuribori/django_rest_captcha_validator

Django REST CAPTCHA Validator is a Django package that's essentially just CAPTCHA suitable for Django REST framework.

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 <https://github.com/mbi/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 <https://django-simple-captcha.readthedocs.io/en/latest/advanced.html#configuration-toggles>`_.