Skip to main content

A simple Django app to create rest applications

Project description

EASY REST
=========

Easy rest framework is built under django rest framework.

The easy rest adds many useful mixins, and make it very easy to create
rest apps

and to integrate rest apps with existing apps

Links:
======

```Contributing`` </CONTRIBUTING.md>`__ :bust\_in\_silhouette:

```Wiki`` <https://github.com/jonatanSh/django-easy-rest/wiki>`__

# Quick start
-------------

1. install using pip:

.. code:: !sh

pip3 install django-easy-rest

2. Add "easy\_rest" to your INSTALLED\_APPS setting like this::

INSTALLED\_APPS = [ ... 'easy\_rest',]

3. Include the easy\_rest URLconf in your project urls.py like this::

url(r'^easy\_rest/', include('easy\_rest.urls')),

4. Configure the url root of easy rest in your project settings.py like
this::

EASY\_REST\_ROOT\_URL = "easy\_rest"

Demo
====

1. clone this repo

2. install easy rest by

.. code:: !sh

pip3 install django-easy-rest

3. head to demo and execute

.. code:: !sh

python3 manage.py migrate

4. create your self a superuser by:

.. code:: !sh

python3 manage.py createsuperuser

5. that's all now run the server by:

.. code:: !sh

python3 manage.py runserver

easy rest mixins:
=================

1. ApiAbstractionsMixin

2. DecorativeKeysMixin

3. HelpMixin

4. FormPostMixin

5. FunctionUnPackerMixin

6. ModelUnpacker

easy rest views:
================

1. RestApiView

easy rest template-tags:
========================

1. {% load\_rest\_scripts %}

2. {% load\_rest\_all %}

more features:
==============

1. auto testing

example of the rest view:
=========================

In this example you are going to learn how to write

class based view using the rest mixin.

This example also shows the power of the easy rest

Code:
=====

views.py

.. code:: python


from easy_rest import views
from easy_rest.mixins import MethodApiHelpMixin,DecorativeKeysMethodApi

class MethodBased(HelpMixin, DecorativeKeysMixin, FunctionUnPackerMixin, ModelUnpacker, views.RestApiView):
method_helpers = {'get_username': {"help": {"general": "returns the username of the requested user",
"general_usage": "suggestting to use the model unpacker mixin"}}}
def get_username(self, user):
return {"username": user.username}

and that's it

Preview
=======

input

.. code:: json

{"action":"get_username", "with-model": {"field":"auth.User", "query":{"pk":1}}}

output (debug mode)

.. code:: json


{
"debug": {
"processed-data": {
"user": {
"_state": {
"db": "default",
"adding": false
},
"first_name": "",
"is_superuser": true,
"is_staff": true,
"last_login": "2017-07-23T11:49:41.804352Z",
"is_active": true,
"email": "jonatanshimon@gmail.com",
"id": 1,
"date_joined": "2017-07-21T19:02:39.414653Z",
"username": "jonatan",
"last_name": "",
"_password": null,
"password": "..."
},
"action": "get_username"
}
},
"data": {
"username": "jonatan"
}
}

as we can see the unpacker got the user with a pk of 1

and returned it to the function because the call was made under debug
mode the easy-rest

returned a debug field in the data, with useful information about the
current query.

Additional fields:
==================

1. query many users into a users variable

.. code:: json

{"action":"get_username", "with-model": [{"field":"auth.User", "query":{"pk":1}, "name":"users"},
{"field":"auth.User", "query":{"pk":2}, "name":"users"}]}

this will return a list called users into a function containing two
models,

a user with a pk of 1 and a user with the pk of 2

2. help and errors

the following input will raise an error because field contains app.model

.. code:: json

{"action":"get_username", "with-model": {"field":"User", "query":{"pk":1}}}

easy rest will add the following to the ouput:

.. code:: json

"help": {
"help-list": "available help entries dict_keys(['general', 'general_usage'])",
"message": "returns the username of the requested user",
"general_usage": "specific help use {action:'get_username', help-prefix:'general_usage'}"
}

for a more complex help we can use the following command

.. code:: json

{"action":"get_username", "with-model": {"field":"User", "query":{"pk":1}}, "help-prefix":"general_usage"}

the output is:

.. code:: json

"help": {
"help-list": "available help entries dict_keys(['general', 'general_usage'])",
"message": "suggestting to use the model unpacker mixin",
"general_usage": "specific help use {action:'get_username', help-prefix:'general_usage'}"
}

Integrating rest with django GCBV:
==================================

The following example is django GCBV update view with a rest post

views.py:

.. code:: python


class UpdateViewApi(FormPostMixin, UpdateView):
fields = ['first_name', 'last_name']
template_name = 'easy_rest/test.html'
model = User
success_message = 'model has been changed {}'.format(datetime.now())

def get_object(self, queryset=None):
return User.objects.get(pk=1)

template

.. code:: html

{% load easy_rest %}
<html lang="en">
<head>
{% load_rest_all %}
</head>
<body>
{% include "easy_rest/easy_rest_form.html" with form=form %}
</body>
</html>

That's it now the easy rest will make the form post rest,

the easy rest also adds success message of post and it places form
errors above the form fields.

Auto testing:
=============

1. the auto test creates a test file based on your api posts

# **how to use**\ # add the following to your view

.. code:: python

class ApiTest(PostRecordTestGenerator, RestApiView):
def __init__(self, *args, **kwargs):
super(ApiTest, self).__init__(*args, **kwargs)
self.init_test(app_name='demo_app')

**structure**
=============

this test will generate test.py for your app if not exists already

and will create a file called auto\_generated\_post\_record\_test.py

each api post will be recoded and converted into a test, so you only
need to make api posts in order to create your test files

! remember remove the PostRecordTestGenerator mixin upon done

Mixins:
=======

**FunctionUnPackerMixin**
=========================

::

this mixin is used to unpack json data into python variables

for example unpacking


.. code:: json

{"a":"value of a", "b":"value of b"}

.. code:: python


def test(a, b):
pass

::

give a result of a="value of a", b="value of b"

and the python call is


.. code:: python

test(a="value of a", b="value of b")

\*HelpMixin\*\* #
=================

::

this mixin decorate api errors with a specific or a general error

this mixin can also display specific information about methods in the api

see examples above.


**DecorativeKeysMixin**
=======================

::

this mixin is used to allow api keys translations for example:

without this mixin api calls can be only under the python language convention

example:


.. code:: json

{"action":"read_book"}

::

using this mixin the following can be


.. code:: json

{"action":"read_book"}

{"action":"read book"}

{"action":"read-book"}

{"action":"read:book"}

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-easy-rest-2.5.tar.gz (190.9 kB view hashes)

Uploaded Source

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