django-rester 0.0.4.dev17

Django REST API build helper

Package for creating API with built-in validation and authentication

This product is designed to build API endpoints of varying complexity and nesting.

The core is a view class - BaseApiView (the inheritor of the standard django view)

---

1. settings

DEFAULT settings (may be overridden):

DJANGO_RESTER = {
    'LOGIN_FIELD': 'username',
    'AUTH_BACKEND': 'django_rester.rester_jwt',
    'RESPONSE_STRUCTURE': False,  # here can be a dict with 'success', 'message' and 'data' as a values
}

DJANGO_RESTER_JWT: {
    'SECRET': 'secret_key',
    'EXPIRE': 60 * 60 * 24 * 14,  # seconds
    'AUTH_HEADER': 'Authorization',
    'AUTH_HEADER_PREFIX': 'jwt',
    'ALGORITHM': 'HS256',
    'PAYLOAD_LIST': ['username'],
    'USE_REDIS': False,  # here can be an int value (redis db number)
}

DJANGO_RESTER - django-rester settings:

     LOGIN_FIELD - user login field (default is ‘username’ as in django)

     AUTH_BACKEND - authentication backend*

     RESPONSE_STRUCTURE - use or not @try_response() decorator by default.

DJANGO_RESTER_JWT - JWT authentication settings (in case of ‘RESTER_AUTH_BACKEND’ = ‘django_rester.rester_jwt’)*:

     SECRET - JWT secret key

     EXPIRE - token expiration time (datetime.now() + RESTER_EXPIRATION_DELTA)

     AUTH_HEADER - HTTP headed, which will be used for auth token.

     AUTH_HEADER_PREFIX - prefix for auth token (“Authorization:<prefix> <token>”)

     ALGORITHM - cypher algorithm

     PAYLOAD_LIST - payload list for token encode (will take specified user attributes to create token)

     USE_REDIS - use redis-server to store tokens or not ***

2. built-in statuses

from django_rester.status import ... slightly modified status.py from DRF, it’s simple and easy to understand.

Any statuses used in this documentation are described in that file. *** ##### 3. built-in exceptions:

from django_rester.exceptions import ... you may use those exceptions to interact with @try_response decorator (good example of usage), or in any other way you want

class ResponseError(Exception)

    base exception class, standard Exception inheritor, added response status - HTTP_500_INTERNAL_SERVER_ERROR

class ResponseBadRequest(ResponseError)

    ResponseError inheritor, response status changed to HTTP_400_BAD_REQUEST

class ResponseServerError(ResponseError)

    ResponseError inheritor

class ResponseAuthError(ResponseError)

    ResponseError inheritor, response status changed to HTTP_401_UNAUTHORIZED

class ResponseOkMessage(ResponseError)

    ResponseError inheritor

    acceptable arguments: *, message=’’, data=None, status=HTTP_200_OK

class ResponseFailMessage(ResponseError)

    ResponseError inheritor

    acceptable arguments: *, message=’’, data=None, status=HTTP_500_INTERNAL_SERVER_ERROR

class ResponseBadRequestMsgList(ResponseError)

    ResponseError inheritor

    acceptable arguments: *, messages=None, status=HTTP_400_BAD_REQUEST

    messages could be list, tuple or string. *** ##### 4. permission classes

from django_rester.permission import ... Permission classes created to interact wih @permissions() decorator (good example of usage), or in any other way you want

All permission classes accepts only one argument on init - django view request object.

All permission classes has 2 attributes, defined on init:

check: Bool - returns True or False if request.user may or may not access endpoint method

message: could be a string or list of messages class BasePermission

    contains all base permission methods, it is not recommended to use it directly in projects

class IsAuthenticated(BasePermission)

    check = True if user authenticated and active, else False

class IsAdmin(BasePermission)

    check = True if user authenticated and active and is_superuser, else False

class AllowAny(BasePermission)

    check = True for any user (even anonymous)

---

5. built-in decorators

from django_rester.decorators import ... @permissions()

    accepts permission class or list, tuple of classes.

    if check is passed, then user will be allowed to use endpoint

example:

class Example(BaseApiView):

    @permissions(IsAdmin)
    def post(request, request_data, *args, **kwargs):
        pass

---

6. built-in views

from django_rester.views import ... class BaseApiView(View)

inherits from standard django view.

class attributes:

    auth - authentication backend instance

    request_fields - request validator

class HTTP methods (get, post, put, etc…) accepts next arguments: request, request_data, *args, **kwargs

    request - standard django view request object

    request_data - all received request parameters as json serialized object

User authentication with selected authentication backend class Login(BaseApiView)

Could be used to authenticate user with selected authentication backend.

    Allowed method is ‘POST’ only.

    Requires username and password in request parameters (username fieldname parameter may be set in settings)

    Returns token and HTTP_200_OK status code if authentication success, error message and HTTP_401_UNAUTHORIZED if failed class Logout(BaseApiView)

Could be used to logout (with redis support) or just to let know frontend about logout process. Any view could be used the same way, here is a simple example:

    app/views.py:

from django_rester.views import BaseAPIView
from django_rester.decorators import permissions
from django_rester.exceptions import ResponseOkMessage
from django_rester.permission import IsAdmin
from django_rester.status import HTTP_200_OK
from app.models import Model
from django_rester.fields import JSONField

class TestView(BaseAPIView):

    request_fields = {"POST": {
        "id": JSONField(field_type=int, required=True, ),
        "title": JSONField(field_type=str, required=True, default='some_title'),
        "fk": [{"id": JSONField(field_type=int, required=True)}],
    }}


    def retrieve_items():
        return Model.objects.all()

    def create_item(title):
        item, cre = Model.objects.get_or_create(title=title)
        return item, cre

    @permissions(AllowAny)
    def get(self, request, request_data, *args, **kwargs):
        items = self.retrieve_items()
        response_data = {...here we should build some response structure...}***
        return response_data, HTTP_200_OK

    @permissions(IsAdmin)
    def post(self, request, request_data, *args, **kwargs):
        title = request_data.get('title', None)
        # no need to check 'if title', because it is allready validated by 'available_fields'
        # ... here we will do some view magic with the rest request_data
        item, cre = self.create_item(title)
        if not cre:
            raise ResponseOkMessage(message='Item allready exists', data={'title': title})
        response_data = {...here we should build some response structure...}***

        return response_data

    app/urls.py:

from django.conf.urls import url
from .views import TestView

urlpatterns = [
    url(r'^test/', TestView.as_view()),
]

---

7. built-in fields

from django_rester.fields import ... class JSONField

class attributes:

    field_type - data type (int, float, str, bool)

    required - field is required

    default - default value if not specified

    blank - may or may not be blank

    model - model for foreign relations

    field - field for foreign relations

methods:

    validate - validate field value with parameters ***

*- There is only one authentication backend available for now - RESTER_JWT

**- BaseApiView is on active development stage, other attributes and methods could be added soon

***- automatic response structure build - one of the nearest tasks