Class-Based Views¶
Django-Bolt supports class-based views for organizing related endpoints. This guide covers APIView, ViewSet, and ModelViewSet.
APIView¶
Use APIView to group HTTP methods for a single resource:
from django_bolt import BoltAPI
from django_bolt.views import APIView
api = BoltAPI()
@api.view("/hello")
class HelloView(APIView):
async def get(self, request):
return {"message": "Hello"}
async def post(self, request, name: str):
return {"message": f"Hello, {name}"}
This creates:
GET /hello- Calls thegetmethodPOST /hello- Calls thepostmethod
Bolt passes the request to the parameter with the name request or req, at each position. self.request is the same request. A method with no such parameter can still read self.request:
@api.view("/whoami")
class WhoAmIView(APIView):
async def get(self):
return {"path": self.request.path}
Available methods¶
Implement any of these methods:
@api.view("/resource")
class ResourceView(APIView):
async def get(self, request):
"""Handle GET requests"""
return {"method": "GET"}
async def post(self, request):
"""Handle POST requests"""
return {"method": "POST"}
async def put(self, request):
"""Handle PUT requests"""
return {"method": "PUT"}
async def patch(self, request):
"""Handle PATCH requests"""
return {"method": "PATCH"}
async def delete(self, request):
"""Handle DELETE requests"""
return {"method": "DELETE"}
async def query(self, request):
"""Handle QUERY requests (a read that takes a request body)"""
return {"method": "QUERY"}
Class-level configuration¶
Set authentication and permissions at the class level:
from django_bolt.auth import JWTAuthentication, IsAuthenticated
@api.view("/protected")
class ProtectedView(APIView):
auth = [JWTAuthentication()]
guards = [IsAuthenticated()]
async def get(self, request):
return {"user_id": request.user.id}
Path parameters¶
Handle path parameters in your methods:
@api.view("/users/{user_id}")
class UserView(APIView):
async def get(self, request, user_id: int):
return {"user_id": user_id}
async def put(self, request, user_id: int, data: UserUpdate):
return {"user_id": user_id, "updated": True}
ViewSet¶
ViewSet provides a higher-level abstraction for CRUD operations:
from django_bolt.views import ViewSet
@api.viewset("/items")
class ItemViewSet(ViewSet):
async def list(self, request) -> list[dict]:
"""GET /items"""
return [{"id": 1}, {"id": 2}]
async def retrieve(self, request, pk: int) -> dict:
"""GET /items/{pk}"""
return {"id": pk}
async def create(self, request, item: ItemCreate) -> dict:
"""POST /items"""
return {"id": 1, "created": True}
async def update(self, request, pk: int, item: ItemUpdate) -> dict:
"""PUT /items/{pk}"""
return {"id": pk, "updated": True}
async def partial_update(self, request, pk: int, item: ItemPatch) -> dict:
"""PATCH /items/{pk}"""
return {"id": pk, "patched": True}
async def destroy(self, request, pk: int):
"""DELETE /items/{pk}"""
return None
This creates:
| Method | URL | Action |
|---|---|---|
| GET | /items |
list |
| POST | /items |
create |
| GET | /items/{pk} |
retrieve |
| PUT | /items/{pk} |
update |
| PATCH | /items/{pk} |
partial_update |
| DELETE | /items/{pk} |
destroy |
An action can be async def or def. Bolt registers only the actions that the class defines.
Set pagination_class on a ViewSet, ReadOnlyModelViewSet, or ModelViewSet
to have the list() action paginated automatically. Use @paginate(...) when
you want per-method control instead.
ModelViewSet¶
ModelViewSet provides built-in Django ORM integration:
from django_bolt import ModelViewSet, PageNumberPagination
from django_bolt.serializers import Serializer
from myapp.models import Article
class ArticleSchema(Serializer):
id: int
title: str
content: str
class ArticleCreateSchema(Serializer):
title: str
content: str
@api.viewset("/articles")
class ArticleViewSet(ModelViewSet):
queryset = Article.objects.all()
serializer_class = ArticleSchema
create_serializer_class = ArticleCreateSchema
pagination_class = PageNumberPagination
The create action only inserts. A primary key or a unique value that a row already has answers 409 Conflict, and the row does not change. perform_create() saves with force_insert=True. If you override perform_create(), call super().perform_create(obj) or save with force_insert=True to keep this.
Serializer output¶
When serializer_class is a Serializer, generated list and retrieve
actions render models through from_model() + dump(). This preserves computed
fields, inherited fields, write_only exclusions, aliases, source mapping,
and nested serializers.
Plain msgspec.Struct response models still use the faster QuerySet.values()
projection path for raw column output.
Request body errors¶
The generated create, update and partial_update actions validate the
request body as a function route does for a body parameter of the same
serializer. A bad body gives the same 422 response. The response reports the
first error of the body:
{
"detail": [
{
"loc": ["body", "title"],
"msg": "Object missing required field `title`",
"type": "missing_field"
}
]
}
get_queryset¶
Override to customize the queryset:
@api.viewset("/my-articles")
class MyArticleViewSet(ModelViewSet):
queryset = Article.objects.all()
async def get_queryset(self):
qs = await super().get_queryset()
return qs.filter(author_id=self.request.user.id)
get_object¶
Get a single object by primary key:
async def retrieve(self, request):
article = await self.get_object() # Raises 404 if not found
return ArticleSchema.from_model(article)
By default, get_object() reads the current lookup value from self.request.params.
A value that the lookup field cannot hold, such as abc for an integer primary key, also raises 404.
If you need to resolve an object manually, explicit lookups still work:
Custom lookup field¶
Use a different field for lookups:
@api.viewset("/articles")
class ArticleViewSet(ModelViewSet):
queryset = Article.objects.all()
lookup_field = "slug" # Use slug instead of pk
async def retrieve(self, request):
article = await self.get_object()
return {"slug": article.slug}
You can also give the lookup field at registration. This value has priority over the class attribute and applies to this registration only:
@api.viewset("/articles-by-slug", lookup_field="slug")
class ArticleBySlugViewSet(ModelViewSet):
queryset = Article.objects.all()
serializer_class = ArticleSerializer
Serializer Priority¶
| Action | Validation | Response |
|---|---|---|
list |
list_serializer_class or serializer_class |
|
retrieve |
serializer_class |
|
create |
create_serializer_class or serializer_class |
serializer_class |
update / partial_update |
update_serializer_class or create_serializer_class or serializer_class |
serializer_class |
Warning
Automatic response-model inference needs either a return type annotation or an available serializer class. Default CRUD helpers still require the corresponding serializer class when they validate request data.
Custom actions¶
Add custom actions using the @action decorator to create endpoints beyond standard CRUD operations.
Basic actions¶
from django_bolt import action
@api.viewset("/articles")
class ArticleViewSet(ViewSet):
queryset = Article.objects.all()
@action(methods=["GET"], detail=False)
async def published(self, request):
"""Collection action: GET /articles/published"""
articles = []
async for article in Article.objects.filter(is_published=True):
articles.append({"id": article.id, "title": article.title})
return articles
@action(methods=["POST"], detail=True)
async def publish(self, request, pk: int):
"""Instance action: POST /articles/{pk}/publish"""
article = await self.get_object()
article.is_published = True
await article.asave()
return {"published": True, "article_id": article.id}
Action parameters¶
| Parameter | Required | Description |
|---|---|---|
methods |
yes | List of HTTP methods: ["GET"], ["POST"], etc. |
detail |
yes | True for instance actions (/{pk}/action), False for collection actions (/action) |
path |
no | Custom URL path (defaults to function name) |
name |
no | URL-reverse suffix; combined with the viewset base as {base}-{name} (see below) |
auth |
no | List of authentication backends (overrides class-level auth) |
guards |
no | List of permission guards (overrides class-level guards) |
response_model |
no | Response model for serialization |
status_code |
no | HTTP status code |
tags |
no | List of tags for OpenAPI documentation |
summary |
no | Summary for OpenAPI documentation |
description |
no | Detailed description for OpenAPI documentation |
An action with no auth, guards, status_code, validate_response or tags uses the value of @api.viewset(...). For auth, guards, status_code and validate_response, the class attribute comes next.
@api.viewset("/articles", auth=[JWTAuthentication()], guards=[IsAuthenticated()])
class ArticleViewSet(ViewSet):
@action(methods=["POST"], detail=True)
async def publish(self, request, pk: int): # Needs a valid token
...
@action(methods=["GET"], detail=False, auth=[], guards=[AllowAny()])
async def featured(self, request): # Public
...
Custom path¶
Override the URL path:
@action(methods=["POST"], detail=True, path="custom-action-name")
async def some_method_name(self, request, pk: int):
"""POST /articles/{pk}/custom-action-name"""
return {"action": "custom-action-name", "article_id": pk}
URL reversing¶
view(), viewset(), and @action all accept name= for URL reversing. A viewset names each route {base}-{action} (e.g. user-list, user-recent). See URL names and reversing for the full reference.
Actions with query parameters¶
@action(methods=["GET"], detail=False)
async def search(self, request, query: str, limit: int = 10):
"""GET /articles/search?query=xxx&limit=5"""
articles = []
async for article in Article.objects.filter(title__icontains=query)[:limit]:
articles.append({"id": article.id, "title": article.title})
return {"query": query, "limit": limit, "results": articles}
Actions with request body¶
import msgspec
class StatusUpdate(msgspec.Struct):
is_published: bool
@action(methods=["POST"], detail=True, path="status")
async def update_status(self, request, pk: int, data: StatusUpdate):
"""POST /articles/{pk}/status with JSON body"""
article = await self.get_object()
article.is_published = data.is_published
await article.asave()
return {"updated": True, "is_published": article.is_published}
Multiple methods on same path¶
Create separate actions for different HTTP methods on the same path:
@action(methods=["GET"], detail=True, path="status")
async def get_status(self, request, pk: int):
"""GET /articles/{pk}/status"""
article = await self.get_object()
return {"is_published": article.is_published}
@action(methods=["POST"], detail=True, path="status")
async def update_status(self, request, pk: int, data: StatusUpdate):
"""POST /articles/{pk}/status"""
article = await self.get_object()
article.is_published = data.is_published
await article.asave()
return {"updated": True}
Custom lookup field with actions¶
Actions respect the ViewSet's lookup_field:
@api.viewset("/articles")
class ArticleViewSet(ViewSet):
queryset = Article.objects.all()
lookup_field = 'id' # Use 'id' instead of 'pk'
async def retrieve(self, request):
"""GET /articles/{id}"""
article = await self.get_object()
return {"id": article.id, "title": article.title}
@action(methods=["POST"], detail=True)
async def feature(self, request, id: int):
"""POST /articles/{id}/feature"""
return {"featured": True, "article_id": id}
Important: Actions require api.viewset()¶
The @action decorator only works with api.viewset(), not api.view():
# CORRECT: Use api.viewset()
@api.viewset("/articles")
class ArticleViewSet(ViewSet):
@action(methods=["POST"], detail=False)
async def custom_action(self, request):
return {"ok": True}
# WRONG: Will raise ValueError
@api.view("/articles", methods=["GET"])
class ArticleView(ViewSet):
@action(methods=["POST"], detail=False) # Error!
async def custom_action(self, request):
return {"ok": True}
Mixins¶
Use mixins to compose functionality:
from django_bolt.views import (
ListMixin,
RetrieveMixin,
CreateMixin,
UpdateMixin,
PartialUpdateMixin,
DestroyMixin,
ViewSet,
)
# Read-only viewset
@api.viewset("/readonly-items")
class ReadOnlyItemViewSet(ListMixin, RetrieveMixin, ViewSet):
queryset = Item.objects.all()
serializer_class = ItemSerializer
# Full CRUD viewset
@api.viewset("/items")
class ItemViewSet(
ListMixin,
RetrieveMixin,
CreateMixin,
UpdateMixin,
PartialUpdateMixin,
DestroyMixin,
ViewSet,
):
queryset = Item.objects.all()
serializer_class = ItemSerializer
Available mixins:
| Mixin | Action | URL | Method |
|---|---|---|---|
ListMixin |
list |
/items |
GET |
RetrieveMixin |
retrieve |
/items/{pk} |
GET |
CreateMixin |
create |
/items |
POST |
UpdateMixin |
update |
/items/{pk} |
PUT |
PartialUpdateMixin |
partial_update |
/items/{pk} |
PATCH |
DestroyMixin |
destroy |
/items/{pk} |
DELETE |
The write actions do not take each field from the request body:
updateandpartial_updatewrite to the object thatget_object()returns. They do not write the primary key, the lookup field or aread_onlyserializer field. Thus the body cannot move the write to a row outsideget_queryset().createdoes not write aread_onlyserializer field. It does not write the primary key when the database gives the primary key (AutoField,BigAutoField).
ReadOnlyModelViewSet¶
A convenient shortcut for read-only access:
from django_bolt.views import ReadOnlyModelViewSet
@api.viewset("/public-articles")
class PublicArticleViewSet(ReadOnlyModelViewSet):
queryset = Article.objects.filter(published=True)
serializer_class = ItemSerializer
This provides only list and retrieve actions.
Sync handlers¶
APIView support synchronous handlers:
@api.view("/sync-resource")
class SyncResourceView(APIView):
def get(self, request): # Note: not async
return {"sync": True}
@action decorators on ViewSet and ModelViewSet also support synchronous handlers:
@api.viewset("/sync-items")
class SyncItemViewSet(ViewSet):
@action(methods=["GET"], detail=False)
def sync(self, request):
return {"sync": True}
Sync handlers are automatically wrapped to run in a thread pool.
Warning
CRUD methods on ViewSets (list, retrieve, create, update, partial_update, destroy) currently do not support synchronous handlers.