To run this project you need to install Docker and Docker Compose.

In this article are the details to install Docker and Docker Compose on a Linux machine. In case you want to install the tools on another platform or have any problems, you can read the official documentation of Docker and also that of Docker Compose.

Continue with downloading the code when you have the dependencies installed and working.

To download the code, the best thing to do is to fork this project to your personal account by clicking on this link. Once you have the fork to your account, download it from the terminal with this command (remember to put your username in the link):

git clone https://github.com/USER/django-rest-api.git

In case you don't have a Github account, or you don't want to fork, you can directly clone this repo with the command git clone https://github.com/gotoiot/service-django-rest-api.git.

To run the application, you first need to download the database image with the docker-compose pull db command. Next, you need to compile the REST API service with the docker-compose build django-rest-api command (it may take a few minutes).

When the above processes finish, start the database service with the command docker-compose up -d db from the root of the project. With the database running, it is necessary to create the tables that the application needs to work with the command docker-compose run django-rest-api python manage.py migrate.

It is possible to include sample data to test the API as quickly as possible. The sample data is in the .fixtures directory. The command needed for load fixture is as follows (in the example, the assesments.json fixtures will be loaded):

docker-compose run django-rest-api python manage.py loaddata .fixtures/assesments.json

With the initial configurations done, it is time to run the API service with the command docker-compose up django-rest-api (if you want to run the service in background, you can add the -d flag during execution). When the service starts, you can access the Browsable API from the browser by entering the api root endpoint in the browser.

If you are able to access the Browsable API, it means that the application is running correctly.

Below you can see the main features of the project:

• RESTful API fully explorable through the "Browsable API" and hyperlinks
• User registration, login, logout, password recovery, account activation
• User email as a unique source of truth
• Application administration panel
• Customized Browsable API for each endpoint
• Extensive usage documentation
• Configurable pagination

The feature related to each application is included in the Applications section.

In the file djangorestapi/settings.py you will find the general configuration of the Django project. Within this file, all kinds of Django configurations can be made, in which the following stand out:

• Selection and configuration of the database engine.
• Applications installed within the project.
• Time zone setting.
• Project debug configuration.
• Django REST Framework specific configuration.
• Template configuration.
• Directory configuration for static files.
• User model selection.
• User Authentication & Authorization.

For more information on all the possible configurations, you can access the official documentation at this link.

This application - by using Django REST Framework - has a functionality that makes the REST API browsable in HTML format. This feature is really an excellent functionality, as it enables you to explore, navigate, and discover the API without having to open any dedicated programs (such as Postman or other clients).

From the browsable API you can access to Home Endpoint, and navigate over the user registration, login, logout, password recovery and email confirmation flows.

The usage flow related of each application is included in its Applications section.

The starting point of using the API is accessing its root via a client or a browser. From there you can see some useful endpoints related to user registration, login, logout and probably your custom applications endpoints.

User Registration, Verification & Login

1. Access to the root endpoint to explore the service endpoints.
2. Access to the user registration endpoint to create an user account. Fill fields with your email and insert twice an strong password.
3. Verify your account via email accessing to the link shown in the console after registration.
4. Access to the email verification and insert your email and password. An access tokens will be returned. You can save it for your mobile/web/desktop app. If you are using the Browsable API the user will be logged in.
5. Go to root endpoint and explore applications endpoints.

User Logout

To logout just follow the user logout endpoint and send a POST request.

User Password Reset

If you have forgotten your password, you can recover it accessing to the password change endpoint. Follow the next steps:

1. Insert your email and send it via POST.
2. Check your email or the "django console email" to access to the link to password change.
3. Insert the needed fields. UID is the anteultimate URL slug, and the Token field is the last URL slug (probaby the token slug includes a "-" char). After required fields just type your new password twice and POST it.

Applications flows

The specific app endpoints are described in each section of Applications.

The API service has an integrated administration panel that allows you to perform CRUD operations on each of registered applications models (tables). In this image you can see how the administration panel looks.

To use the admin site you must create a superuser before. Execute the command docker-compose run django-rest-api python manage.py createsuperuser, enter your email and your password twice and then go to admin endpoint to login with your credentials.

There are many sections included in the admin, like Accounts, Tokens, Sites, Social Accounts and Users. This applications are included in the base project to provide user auth flows.

Apart of the base sections, there are the custom applications, explained in the Applications section.

Some environment variables used by the database service, as well as the API service, are defined in the env file. Necessary variables can be added/removed. In case you accidentally delete the values or the env file, below you can find some values that work correctly with the application.

DJANGO_SECRET_KEY=sup3rs3cr3tk3y
DJANGO_DEBUG=True
DATABASE_NAME=codedb
DATABASE_USER=postgres
DATABASE_PASS=postgres
DATABASE_HOST=db
DATABASE_PORT=5432
LOGLEVEL=info
ACCESS_TOKEN_LIFETIME=120

It is HIGHLY RECOMMENDEDthat you change these variables if you want to use this application for productive purposes.

Django provides an excellent database manipulation without the need to use any external tools to perform the necessary operations.

If you want to make a simple backup of the database, execute the following command:

docker-compose run django-rest-api \
python manage.py dumpdata --indent 2 > .fixtures/db.json

If you want to make a backup of the database that can be used in a fresh database, execute the following command:

docker-compose run django-rest-api \
python manage.py dumpdata --indent 2 \
--exclude auth.permission --exclude contenttypes --exclude admin.logentry > .fixtures/db.json

To load the application data into a fresh database, run the following command to create the necessary tables:

docker-compose run django-rest-api python manage.py migrate

And then load data inside the tables:

docker-compose run django-rest-api python manage.py loaddata .fixtures/db.json

The base structure is as follows:

├── .fixtures                       # dir to save DB fixtures to export/import using Django manage.py
├── users                           # main users app dir
│   ├── migrations                  # dir to track DB modifications
│   ├── admin.py                    # register user model into admin interface
│   ├── apps.py                     # register user app into Django
│   ├── managers.py                 # classes for serialize/deserialize models instances
│   ├── models.py                   # user models declaration
│   ├── serializers.py              # classes for serialize/deserialize models instances
├── djangorestapi                         # main Django project
│   ├── asgi.py                     # utility to load Django app into ASGI servers
│   ├── settings.py                 # main Django project settings
│   ├── urls.py                     # main Django project URLs configuration
│   |── wsgi.py                     # utility to load Django app into WSGI servers
│   └── views.py                    # main service endpoints (home)
├── doc                             # dir to save documentation
│   └── ...
├── .gitignore                      # exclude files from versions control
├── .dockerignore                   # exclude files when build a docker image
├── CHANGELOG.md                    # project changes history and descriptions
├── Contribuitors.md                # project contribuitors
├── Dockerfile                      # Dockerfile for Django project
├── LICENSE                         # licencia del proyecto
├── README.md                       # este archivo
├── docker-compose.yml              # configuración de los contenedores de Docker centralizada
├── env                             # variables de entorno utilizadas en el proyecto
├── manage.py                       # archivo con utilidades nativas de Django
└── requirements.txt                # dependencias de Python del proyecto

Custom applications structure are not included.

The Assesments API has needed functionality to permorm assesments and create its questions, options, and their relations.

• Run the application with a productive web server: For the development and demonstration of the application, the Django development web server is used. If you want to implement a productive server, in this link, for example, there is information to configure uWSGI.
• SSL encryption: This project is for demonstration purposes, and also uses the development web server provided by Django. If you want to bring this project to a productive environment, SSL should be implemented in the webserver used. For example, in this link you will find information on how to configure certificates in Nginx. Also, in this link there is a tutorial on how to enable HTTPS using the Django development server.
• Compress responses: If a productive web server were used, compression of the responses could be performed. In this link there is a tutorial to enable Gzip on an Nginx server.
• Support other formats than text in DB: In this API they only supported format is text based. If you wanted to save an image or other file, it could be hosted in an S3 bucket and only save the URL in the field.
• Automated testing: Although having automated testing is a totally necessary feature, it was not implemented for this project. Implementing unit testing is not too complex. If you want to implement it, in this link you will find all the necessary information.
• Capture update signals for ApiUsers: At this moment, if you update some user data from de admin site, it doesn't impact in the EmailAddress table, which is used for whole user authentication. The update signal must be catched and perform the EmailAddress update as well.
• Add logging: at this momment, the service doesn't have logging features, but it could be a really good idea to include it.

• Docker - Ecosystem that allows the execution of software containers.
• Docker Compose - Tool that allows managing multiple Docker containers.
• Python - Language in which the services are made.
• Django - Popular Python framework for web application development.
• Django REST Framework - Django-based framework for designing REST APIs.
• PostgreSQL - Database to query and store data.
• Visual Studio Code - Popular multi-platform development IDE.