Django Headless

With Django Headless you quickly create a REST API for your models, making it easy to turn Django into a powerful headless CMS.

📖 Read the full documentation at djangoheadless.org

✨ Features

• 🎯 Easy configuration: Add @expose decorator to any model and get instant REST endpoints
• 🤝 Plays nice: Seamlessly integrates with existing Django applications
• 💈 Supports singletons: Special handling for singleton models (settings, configurations, etc.)
• 🔍 Flexible filtering: Filtering backend based on Django ORM lookups, enabled by default
• 🛡️ Secure by default: Generated routes require authentication until you open them up

🚀 Quick Start

Install the package:

pip install django-headless

Add headless to INSTALLED_APPS:

# settings.py
INSTALLED_APPS = [
    # ...
    "rest_framework",
    "headless",
]

Expose a model:

# apps/blog/models.py
from django.db import models
from headless import expose


@expose()
class BlogPost(models.Model):
    title = models.CharField(max_length=200)
    content = models.TextField()
    published = models.BooleanField(default=False)
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.title

Include the URLs:

# urls.py
from django.urls import path, include

urlpatterns = [
    # ...
    path("api/", include("headless.rest.urls")),
]

That's it! 🎉 Your model is now available via REST API at /api/blog.blogpost

Note: generated routes answer 403 for unauthenticated requests by default, so freshly exposed models are never accidentally public. See the permissions documentation to open routes up.

📚 Documentation

All usage and configuration is documented at djangoheadless.org:

• Installation — requirements, setup and first steps
• Exposing models — all @expose() options: singletons, field control, read-only models
• Singletons — single-instance resources like site settings
• Filtering — ORM lookups, exclusions and type casting
• Pagination — the read-friendly pagination envelope
• Authentication — secret key authentication and DRF classes
• Permissions — safe defaults and route-scoped overrides
• Serializers — serializer customization, field expansion and model properties
• Settings reference — every HEADLESS option

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for your changes
5. Run the test suite (poetry run test)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/dwarsbit/django-headless.git
cd django-headless

# Install dependencies (Poetry creates the virtual environment)
poetry install

# Run tests
poetry run test

🐛 Issues & Support

• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: leon@dwarsbit.nl

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built on the shoulders of Django and Django REST Framework
• Inspired by the headless CMS and Jamstack movement
• Thanks to all contributors and the Django community

🔗 Links

• Documentation
• PyPI Package
• GitHub Repository
• Changelog