Skip to main content

Django REST API build helper

Project description

build codacy pypi license

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. requirements

  1. Python 3+

  2. Django 1.11+


2. settings

DEFAULT settings (may be overridden):

DJANGO_RESTER = {
    'AUTH_BACKEND': 'django_rester.rester_jwt',
    'RESPONSE_STRUCTURE': False,
    'CORS_ACCESS': False,
    'FIELDS_CHECK_EXCLUDED_METHODS': ['OPTIONS', 'HEAD'],
    'SOFT_RESPONSE_VALIDATION': False,
}

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)
    'LOGIN_FIELD': 'username', # as default django login field
}

DJANGO_RESTER - django-rester settings:

     AUTH_BACKEND - authentication backend*

     RESPONSE_STRUCTURE - Either False or a dict with ‘success’, ‘message’ and ‘data’ as a values

     CORS_ACCESS - CORS control: True, False, ‘*’, hosts_string

     FIELDS_CHECK_EXCLUDED_METHODS - methods, which will not be processed with body structure checks

     SOFT_RESPONSE_VALIDATION - if True, response will not be cut off if it will contain additional to response_structure fields

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

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

3. 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. *** ##### 4. built-in exceptions:

from django_rester.exceptions import ... Exceptions, which will help you to recognise errors related to django-rester

class ResterException(Exception)

    base django-rester exception, standard Exception inheritor

class ResponseError(Exception)

    ResponseError 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.

class JSONFieldError(ResterException)

    ResterException inheritor, base JSONField exception

class JSONFieldModelTypeError(JSONFieldError)

    JSONField exception, raises when type of model parameter is not valid

class JSONFieldModelError(JSONFieldError)

    JSONField exception, raises when value of model parameter is not valid

class JSONFieldTypeError(JSONFieldError)

    JSONField exception, simple TypeError inside JSONField class

class JSONFieldValueError(JSONFieldError)

    JSONField exception, simple ValueError inside JSONField class

class BaseAPIViewException(Exception)

    BaseAPIView exception class

class RequestStructureException(BaseAPIViewException)

    raise if request structure is invalid

class ResponseStructureException(RequestStructureException)

    raise if response structure is invalid *** ##### 5. 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)


6. 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

7. 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 (use JSONField to build this validator)

    response_fields - response validator (use JSONField to build this 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 # import Model from your application
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)}],
    }}

    response_fields = {"POST": {
        "id": JSONField(field_type=int, required=True, ),
        "title": JSONField(field_type=str, required=True, default='some_title'),
        # ...
    }}

    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()),
]

8. 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 (public), with normal usage, you won’t need them in your code:

    check_type - validate type of JSONField value

    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

Installation notes

pycurl (Mac OS)

brew remove curl
brew install curl-openssl
export PYCURL_SSL_LIBRARY=openssl
pip install --no-cache-dir --global-option=build_ext --global-option="-L/usr/local/opt/openssl/lib" --global-option="-I/usr/local/opt/openssl/include" --compile --install-option="--with-openssl" pycurl

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-rester-0.0.6.36.tar.gz (18.0 kB view details)

Uploaded Source

Built Distribution

django_rester-0.0.6.36-py3-none-any.whl (21.5 kB view details)

Uploaded Python 3

File details

Details for the file django-rester-0.0.6.36.tar.gz.

File metadata

  • Download URL: django-rester-0.0.6.36.tar.gz
  • Upload date:
  • Size: 18.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.21.0 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.31.1 CPython/3.5.6

File hashes

Hashes for django-rester-0.0.6.36.tar.gz
Algorithm Hash digest
SHA256 ad1cf76c28226a73eafce2b370a470ab3c87de8daaac6f2d1df2b6c1f297f49a
MD5 0e983aa3c3be80c4b225c018bfd533cf
BLAKE2b-256 2101615efc26ce80e09e95a0764e73a904dc651bf979cfad56beca0aa3a0e780

See more details on using hashes here.

File details

Details for the file django_rester-0.0.6.36-py3-none-any.whl.

File metadata

  • Download URL: django_rester-0.0.6.36-py3-none-any.whl
  • Upload date:
  • Size: 21.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.21.0 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.31.1 CPython/3.5.6

File hashes

Hashes for django_rester-0.0.6.36-py3-none-any.whl
Algorithm Hash digest
SHA256 e47223bdd6bb83378c1f940b838fa984da5144cffa7bd51452405728c8ca28fe
MD5 30750875f7bb31d6890fc0c9c51a43e1
BLAKE2b-256 73cc8c23608a5bf89faf726fedc300227b669c455afd63feaadc2caae5d34295

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page