YADRTA

Yet Another Djando REST Todo App using django rest and django with OpenAPI Specification. The purpose of this project is to show minimal best practices including tests.

Demo

View Demo: https://yadrta.herokuapp.com

swagger

redoc

django rest api

Table of Contents

• Demo
• Table of Contents
• General
  • Endpoints
  • Branches
  • Prerequisites
• Getting Up and Running Locally
  • Installing
  • Setting Up Development Environment
  • Code Quality
  • Summary
• Usage
  • Authentication
    • Create User
    • Create Superuser
    • Getting User Token
    • Login
  • API v1
    • Sample API Responses
• Testing
  • Test Coverage
• Versioning
• Authors
• License

General

Endpoints

This app gets requests from localhost on port 8000 and performs CRUD operations.

Base endpoints are:

• The base endpoint is: http://localhost:8000 | https://yadrta.herokuapp.com
• base_url for API v1 is /api/v1/
• Session Authentication: /api-auth/login/ /api-auth/logout/
• Admin panels: /admin/

CRUD API endpoints:

• /api/v1/category/
• /api/v1/tag/
• /api/v1/todo/

For documemtation:

• /api/v1/doc/swagger/
• /api/v1/doc/swagger.yaml
• /api/v1/doc/swagger.json
• /api/v1/doc/redoc/

Branches

• master - default branch
• basic - using django's default basic structure
• local - just for local development
• others - feature branches wip

Prerequisites

• Python 3.8

Getting Up and Running Locally

Installing

Clone the repo with ssh:

$ git clone https://github.com/SerhatTeker/yadrta.git

or with https:

$ git clone git@github.com:SerhatTeker/yadrta.git

Setting Up Development Environment

1. Create a virtualenv:

   $ virtualenv -p python3.8 .venv

2. Activate the virtualenv you have just created:

   $ source .venv/bin/activate

3. Install development requirements:

   $ pip install -r requirements/local.txt

4. Apply migrations:

   $ python manage.py migrate

5. Run Django development server:

   $ python manage.py runserver 8000

Make Way

You can use Makefile to complete the all processes above, just run:

```bash
$ make startproject
$ make runserver
```

Code Quality

For code quality this repo uses pre-commit: A framework for managing and maintaining multi-language pre-commit hooks.

Configuration file can be found: .pre-commit-config.yaml.

To install the git hook script run:

$ pre-commit install

Now pre-commit will run automatically on git commit!

Summary

Congratulations, you have made it!

Usage

Activate virtual environment and run django development server:

$ source .venv/bin/activate
$ python manage.py runserver 8000

Authentication

This app uses 2 different auth methods:

• Session Authentication
• Token Authentication

Create User

$ curl -d '{"username":"testuser", "password":"testuser", "email":"testuser@testapi.com"}' \
	     -H "Content-Type: application/json" \
	     -X POST http://localhost:8000/api/v1/users/

Create Superuser

1. From manage.py cli utility tool:

   $ python manage.py createsuperuser --username testdamin --email testadmin@testapi.com

2. From make target:

   You can use default one from .envs/.local/.django or you can define it manually as below:

   # DJANGO_DEV_ADMIN=name:email:password
   $ export DJANGO_DEV_ADMIN_LOCAL=testadmin:testadmin@testapi.com:123asX3?23

   To create an admin user for local run:

   $ make create-superuser

   which will run:

   @echo "from django.contrib.auth import get_user_model;"\
     "User = get_user_model();" \
     "User.objects.create_superuser(*'$(DJANGO_DEV_ADMIN_LOCAL)'.split(':'))" \
     | $(PYTHON) manage.py shell

Getting User Token

Execute:

$ http http://localhost:8000/api-token-auth/ username=testuser password=testuser

Output will be like:

HTTP/1.1 200 OK
Allow: POST, OPTIONS
Content-Length: 52
Content-Type: application/json
Date: Tue, 22 Sep 2020 13:57:46 GMT
Referrer-Policy: same-origin
Server: WSGIServer/0.2 CPython/3.8.1
Vary: Cookie
X-Content-Type-Options: nosniff
X-Frame-Options: DENY

{
    "token": "80ca0dadab06b34623a6b8279320e8341e2a5102"
}

Login

Use one of the below endpoints:

• /admin/
• /api-auth/login/

API v1

curl:

$ curl -X GET http://localhost:8000/api/v1/todo/ \
		-H 'Authorization: Token <user_token>' \
		-H 'Accept: application/json; indent=4'

After those you will get below todo sample api response:

Sample API Responses

• /category/

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "name": "business",
            "pk": 1,
            "uuid": "d1911f18-8a49-457c-aa72-b1e9ae9e198d",
            "created_by": "1809d5b4-4b71-4b68-9221-73af7a2e221d",
            "created_at": "2020-09-17T15:49:42.392670Z",
            "changed_at": "2020-09-17T15:49:42.392730Z",
        },
        {
            "name": "post",
            "pk": 2,
            "uuid": "d1911f18-8a49-457c-aa72-b1e9ae9e198d",
            "created_by": "1809d5b4-4b71-4b68-9221-73af7a2e221d",
            "created_at": "2020-09-17T15:49:42.392670Z",
            "changed_at": "2020-09-17T15:49:42.392730Z",
        }
    ]
}

• /tag/

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "name": "newthing",
            "pk": 1,
            "uuid": "d1911f18-8a49-457c-aa72-b1e9ae9e198d",
            "created_by": "1809d5b4-4b71-4b68-9221-73af7a2e221d",
            "created_at": "2020-09-17T15:49:42.392670Z",
            "changed_at": "2020-09-17T15:49:42.392730Z",
        },
        {
            "name": "language",
            "pk": 2,
            "uuid": "d1911f18-8a49-457c-aa72-b1e9ae9e198d",
            "created_by": "1809d5b4-4b71-4b68-9221-73af7a2e221d",
            "created_at": "2020-09-17T15:49:42.392670Z",
            "changed_at": "2020-09-17T15:49:42.392730Z",
        }
    ]
}

• /todo/

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "pk": 1,
            "description": "bla bla",
            "uuid": "9d208186-0987-4a7c-a75c-17094b7e6aab",
            "title": "bla bla",
            "status": "todo",
            "tag": 1,
            "category": 1,
            "created_by": "1809d5b4-4b71-4b68-9221-73af7a2e221d",
            "created_at": "2020-09-17T15:52:28.944148Z",
            "changed_at": "2020-09-17T15:52:28.944182Z",
        },
        {
            "pk": 2,
            "title": "bla bla2",
            "description": "bla bla2",
            "status": "todo",
            "tag": 1,
            "category": 1,
            "uuid": "d9a804a6-79c3-40bc-befb-3c0290d1f0c8",
            "created_by": "1809d5b4-4b71-4b68-9221-73af7a2e221d",
            "created_at": "2020-09-17T15:53:05.809323Z",
            "changed_at": "2020-09-17T15:53:05.809356Z",
        }
    ]
}

Testing

Install requirements:

$ pip install -r requirements/local.txt

Run tests:

$ pytest

Test Coverage

To run test with coverage:

$ make test

which will execute:

$ coverage erase
$ coverage run -m pytest
$ coverage report -m
$ coverage html

Then you can look at the produced report file : ./htmlcov/index.html, with your browser.

For instance open with Firefox:

$ firefox ./htmlcov/index.html

Current test coverage:

For a detail report: https://codecov.io/github/SerhatTeker/yadrta?branch=master

Versioning

I use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• Serhat Teker serhatteker

License

This project is licensed under the BSD-3-Clause License - see the LICENSE file for details.