1. Learn more here - https://www.hacksoft.io/blog/django-styleguide-survey - or simply jump to the survey here - https://form.jotform.com/213492755022049.
2. The survey takes 5 to 10 minutes to complete.
3. We will run the survey for 2 months and a half, until the end of February.
4. When the survey is done, 10 participants are going to be picked at random, each of them receiving a $50 Amazon gift card.

This project serves as an example of our styleguide

The structure is inspired by cookiecutter-django and modified based on our experience with Django.

Few important things:

• Linux / Ubuntu is our primary OS and things are tested for that. It will mostly not work on Mac & certainly not work on Windows.
• It uses Postgres as the primary database.
• It comes with GitHub Actions support, based on that article
• It comes with examples for writing tests with fakes & factories, based on the following articles - https://www.hacksoft.io/blog/improve-your-tests-django-fakes-and-factories, https://www.hacksoft.io/blog/improve-your-tests-django-fakes-and-factories-advanced-usage
• It comes with whitenoise setup.
• It can be easily deployed to Heroku or AWS ECS.
• Dockerized for local development with docker-compose.
• It comes with an example list API, that uses django-filter for filtering & pagination from DRF.
• It comes with mypy configured, using both https://github.com/typeddjango/django-stubs and https://github.com/typeddjango/djangorestframework-stubs/
  • Basic mypy configuration is located in setup.cfg
  • mypy is ran as a build step in .github/workflows/django.yml
  • ⚠️ The provided configuration is quite minimal. You should figure out your team needs & configure accordingly - https://mypy.readthedocs.io/en/stable/config_file.html

The project is running django-cors-headers with the following general configuration:

CORS_ALLOW_CREDENTIALS = True
CORS_ALLOW_ALL_ORIGINS = True

For production.py, we have the following:

CORS_ALLOW_ALL_ORIGINS = False
CORS_ORIGIN_WHITELIST = env.list('CORS_ORIGIN_WHITELIST', default=[])

The project is using https://github.com/Styria-Digital/django-rest-framework-jwt for having authentication via JWT capabilities.

All JWT related settings are located in config/settings/jwt.py.

⚠️ We highly recommend reading the entire settings page from the project documentation - https://styria-digital.github.io/django-rest-framework-jwt/#additional-settings - to figure out your needs & the proper defaults for you!

The default settings also include the JWT token as a cookie.

The specific details about how the cookie is set, can be found here - https://github.com/Styria-Digital/django-rest-framework-jwt/blob/master/src/rest_framework_jwt/compat.py#L43

The JWT related APIs are:

1. /api/auth/jwt/login/
2. /api/auth/jwt/logout/

The current implementation of the login API returns just the token:

{
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VybmFtZSI6InJhZG9yYWRvQGhhY2tzb2Z0LmlvIiwiaWF0IjoxNjQxMjIxMDMxLCJleHAiOjE2NDE4MjU4MzEsImp0aSI6ImIyNTEyNmY4LTM3ZDctNGI5NS04Y2M0LTkzZjI3MjE4ZGZkOSIsInVzZXJfaWQiOjJ9.TUoQQPSijO2O_3LN-Pny4wpQp-0rl4lpTs_ulkbxzO4"
}

This can be changed from auth_jwt_response_payload_handler.

We follow this concept:

1. All APIs are public by default (no default authentication classes)
2. If you want a certain API to require authentication, you add the ApiAuthMixin to it.

This project is using the already existing cookie-based session authentication in Django:

1. On successful authentication, Django returns the sessionid cookie:

sessionid=5yic8rov868prmfoin2vhtg4vx35h71p; expires=Tue, 13 Apr 2021 11:17:58 GMT; HttpOnly; Max-Age=1209600; Path=/; SameSite=Lax

2. When making calls from the frontend, don't forget to include credentials. For example, when using axios:

axios.get(url, { withCredentials: true });
axios.post(url, data, { withCredentials: true });

3. For convenience, CSRF_USE_SESSIONS is set to True

4. Check config/settings/sessions.py for all configuration that's related to sessions.

Since the default implementation of SessionAuthentication enforces CSRF check, which is not the desired behavior for our APIs, we've done the following:

from rest_framework.authentication import SessionAuthentication


class CsrfExemptedSessionAuthentication(SessionAuthentication):
    """
    DRF SessionAuthentication is enforcing CSRF, which may be problematic.
    That's why we want to make sure we are exempting any kind of CSRF checks for APIs.
    """
    def enforce_csrf(self, request):
        return

Which is then used to construct an ApiAuthMixin, which marks an API that requires authentication:

from rest_framework.permissions import IsAuthenticated


class ApiAuthMixin:
    authentication_classes = (CsrfExemptedSessionAuthentication, )
    permission_classes = (IsAuthenticated, )

By default, all APIs are public, unless you add the ApiAuthMixin

We have the following general cases:

1. The current configuration works out of the box for localhost development.
2. If the backend is located on *.domain.com and the frontend is located on *.domain.com, the configuration is going to work out of the box.
3. If the backend is located on somedomain.com and the frontend is located on anotherdomain.com, then you'll need to set SESSION_COOKIE_SAMESITE = 'None' and SESSION_COOKIE_SECURE = True

1. POST to /api/auth/session/login/ requires JSON body with email and password.
2. GET to /api/auth/me/ returns the current user information, if the request is authenticated (has the corresponding sessionid cookie)
3. GET or POST to /api/auth/logout/ will remove the sessionid cookie, effectively logging you out.

The current implementation of /api/auth/session/login does 2 things:

1. Sets a HTTP Only cookie with the session id.
2. Returns the actual session id from the JSON payload.

The second thing is required, because Safari is not respecting the SameSite = None option for cookies.

More on the issue here - https://www.chromium.org/updates/same-site/incompatible-clients

Since cookies can be somewhat elusive, check the following urls:

1. https://docs.djangoproject.com/en/3.1/ref/settings/#sessions - It's a good idea to just read every description for SESSION_*
2. https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies - It's a good idea to read everything, several times.

You can find the UserListApi in styleguide_example/users/apis.py

List API is located at:

http://localhost:8000/api/users/

The API can be filtered:

• http://localhost:8000/api/users/?is_admin=True
• http://localhost:8000/api/users/?id=1
• http://localhost:8000/api/users/?email=radorado@hacksoft.io

Example data structure:

{
    "limit": 1,
    "offset": 0,
    "count": 4,
    "next": "http://localhost:8000/api/users/?limit=1&offset=1",
    "previous": null,
    "results": [
        {
            "id": 1,
            "email": "radorado@hacksoft.io",
            "is_admin": false
        }
    ]
}

To create Postgres database:

sudo -u postgres createdb -O your_postgres_user_here database_name_here

If you want to recreate your database, you can use the bootstrap script:

./scripts/bootstrap.sh your_postgres_user_here

To start Celery:

celery -A styleguide_example.tasks worker -l info --without-gossip --without-mingle --without-heartbeat

To start Celery Beat:

celery -A styleguide_example.tasks beat -l info --scheduler django_celery_beat.schedulers:DatabaseScheduler

To build and run everything

docker-compose up

To run migrations

docker-compose run django python manage.py migrate

To shell

docker-compose run django python manage.py shell

The project is ready to be deployed on Heroku. There's a current deployment that can be found - https://hacksoft-styleguide-example.herokuapp.com/