django-api-admin 1.3.0

A RESTful API implementation of django.contrib.admin, designed for writing custom frontends.

Django API Admin

A RESTful API implementation of django.contrib.admin, designed for writing custom frontends.
Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
   • CORS Configuration
   • Authentication
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

About The Project

Django API Admin is a RESTful API implementation of the django.contrib.admin application, designed to make it easy to create custom frontends. This project aims to provide developers with a flexible API that mirrors the functionality of Django's built-in admin interface, allowing for seamless integration with modern web client interfaces.

Key Features:

• RESTful API: Offers a comprehensive API for managing Django models, enabling developers to build custom administrative interfaces.
• Custom Frontends: Designed to support the development of tailored frontends that meet specific project requirements.
• Extensible and Modular: Build with the same django.contrib.admin API, allowing for easy customization and integration with existing Django projects.

The project is continuously evolving, with new features and improvements being added regularly. Contributions from the community are highly encouraged to help expand and enhance the capabilities of this tool.

To get started, follow the installation and usage instructions provided in this README. Whether you're building a new project or integrating with an existing one, Django API Admin offers the flexibility and power you need to manage your application's data effectively.

(back to top)

Built With

This section should list any major frameworks/libraries used to bootstrap your project. Leave any add-ons/plugins for the acknowledgements section. Here are a few examples.

• 
• 
• 

(back to top)

Getting Started

To set up the project locally, follow these steps:

Prerequisites

Before you begin, ensure you have met the following requirements:

• Python 3.12+: Make sure Python is installed on your machine. You can download it from python.org.

• Django REST framework

  pip install djangorestframework
  

• drf-spectacular

  pip install drf-spectacular
  

Installation

This section will walk you through the steps to install django-api-admin in your Django project. Follow these instructions to get started.

1. Install the Package

   pip install django-api-admin
   

2. Add to Installed Apps Add django_api_admin and it's requirements to the INSTALLED_APPS list in your Django project's settings.py file (the order doesn't matter):

   # settings.py
   INSTALLED_APPS = [
      'corsheaders',
      'drf_spectacular',
      'rest_framework',
      'django_api_admin'
   ]
   

3. In your Django settings file, add or update the REST_FRAMEWORK dictionary to include the drf spectacular as the DEFAULT_SCHEMA_CLASS:

   # settings.py
   REST_FRAMEWORK = {
       'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
   }
   

4. Add the modify_schema hook to improve the auto generated openAPI schema

   # settings.py
   SPECTACULAR_SETTINGS = {
       "POSTPROCESSING_HOOKS": [
           'drf_spectacular.hooks.postprocess_schema_enums',
           'django_api_admin.hooks.modify_schema'
       ]
   }
   

Thats it you are now ready to register your models and implement your django admin frontend!

CORS Configuration

If you plan to build a custom frontend in React.js or Vue.js then you might want to consider adding CORS configuration to your Django project. This will allow your frontend to make requests to your Django backend.

1. Install django-cors-headers package

pip install django-cors-headers

2. Add corsheaders to INSTALLED_APPS in your Django project's settings.py file (the order doesn't matter):

   # settings.py
   INSTALLED_APPS = [
      'corsheaders',
      # ...
   ]
   

3. Add the urls of your client side applications to the CORS_ORIGIN_WHITELIST

   # settings.py
   CORS_ORIGIN_WHITELIST = (
       'http://localhost',  # jest-dom test server
       'http://localhost:3000',  # react development server
   )
   CORS_ALLOW_CREDENTIALS = True
   

Your client side application should now be able to make requests to your django backend!

Authentication

Unlike django.contrib.admin this package doesn't include it's own authentication functionality. You will need implement authentication on your own, however the django-api-admin makes it very easy to add support for authentication frameworks that support rest_framework. This is how you can add django-allauth for instance:

1. Install django-allauth

pip install django-allauth

2. Configure django-allauth settings for your project

# settings.py

INSTALLED_APPS = [
    # ...
    'allauth',
]

MIDDLEWARE = [
    # ...
    'allauth.account.middleware.AccountMiddleware',
    # ...
]

AUTHENTICATION_BACKENDS = [
    'django.contrib.auth.backends.ModelBackend',
    'allauth.account.auth_backends.AuthenticationBackend',
]

3. Add the authentication_classes to an APIAdminSite subclass.

from django_api_admin import APIAdminSite

class AdminSite(APIAdminSite):
    def get_authentication_classes(self):
        from allauth.headless.contrib.rest_framework.authentication import XSessionTokenAuthentication

        return [XSessionTokenAuthentication, authentication.SessionAuthentication]

site = AdminSite()

4. include the django-allauth headless urls in your urls.py file.

# urls.py
urlpatterns = [
    # ...
    path("_allauth/", include("allauth.headless.urls")),
]

Now, django-api-admin will use the provided authentication_classes for authenticating users.

(back to top)

Usage

This section provides a simple example on how to use django-api-admin. If you're setting up for the first time, follow the example below to get started.

1. Create some models

   # models.py
   from django.db import models
   
   class Author(models.Model):
       name = models.CharField(max_length=100)
   
       def __str__(self):
           return self.name
   
   class Book(models.Model):
       title = models.CharField(max_length=100)
       author = models.ForeignKey(Author, on_delete=models.CASCADE)
   
       def __str__(self):
           return self.title
   

2. Register them using the admin site

   # admin.py
   from django_api_admin.sites import site
   from .models import Author, Book
   
   site.register(Author)
   site.register(Book)
   

3. Include URLs Include the django-api-admin URLs in your

   # urls.py
   from django.urls import path
   from django_api_admin.sites import site
   
   # the admin site needs to know the name of the url prefix in this case "admin/"
   # the default is just the admin site's name which is "admin" + "/" 
   # for the default admin site
   urlpatterns = [
      path('admin/', site.urls),
   ]
   

(back to top)

Roadmap

• Rewrite django.contrib.admin as an API
• Add support for Bulk Actions
• Add OpenAPI documentation
• Add support for charts
• Add support for global full-text search

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Top Contributors

(back to top)

License

Distributed under the MIT License. See the LICENSE file for more information.

(back to top)

Contact

Muhammad Salah - @daemobixia - [e-mail]

Project Link: https://github.com/demon-bixia/django-api-admin

(back to top)

Acknowledgments

This section is dedicated to recognizing the valuable resources and contributions that have supported this project. Below are some of the key references and inspirations that have been instrumental in the project's development journey.

• Django Web Framework
• Django Rest Framework
• DRF Spectacular
• Best README Template

(back to top)