django-allresponses¶
A Django package that provides response classes for all RFC 9110 HTTP status codes.
Features¶
- Response classes for all RFC 9110 HTTP status codes
- Compatible with Django 4.2 LTS and later versions
- Full test coverage
- Type hints included
Installation¶
Usage¶
All response classes in this package are subclasses of Django's
HttpResponse.
You can use them anywhere you would use a normal HttpResponse, and they work
with Django's middleware and testing tools.
For HTML or other content, use the HttpResponse-prefixed classes:
from django_allresponses import HttpResponseOK, HttpResponseNoContent, HttpResponseCreated
def my_view(request):
# Return a 200 OK response (explicit status)
return HttpResponseOK("<p>Hello</p>")
# Or 204 No Content
return HttpResponseNoContent()
# Or 201 Created with a Location header
return HttpResponseCreated(location='/api/resource/123')
For JSON APIs, use the JsonResponse-prefixed classes (they subclass
Django's
JsonResponse
and set the status code for you):
from django_allresponses import JsonResponseOK, JsonResponseCreated, JsonResponseUnauthorized
def api_view(request):
if not request.user.is_authenticated:
return JsonResponseUnauthorized({"error": "Authentication required"})
data = {"id": 123, "name": "Example"}
return JsonResponseCreated(data, location="/api/items/123")
Why this package?¶
Basically, because Django has a whole bunch of custom HttpResponse subclasses, for BadRequest, for ResponseNotFound, for ResponseNotModified and so on.
But for some very standard response codes such as No Content (HTTP 204) and Created (HTTP 201) there are no subclasses. In RESTy systems I use these response codes all the time.
It feels very arbitrary that some classes exist and others don't.
Of course I can make my own subclass and use that but I would like Django to have it built-in. So I opened a discussion about this:
TL;DR: people do not find it is 'worth it' to add these response codes that are used a lot, because you could just as well write your own, or use the 'generic' HTTPResponse and add a custom code.
That's all fair, but I do think that custom classes have other benefits too. I think it's beneficial to list the responses that you can choose from all in one place, instead of having a specific response for Gone (HTTP 410) but none for Created.
So I went all maximalist and added a complete list of all RFC9110 HTTP status codes as subclasses in this django-allresponses module. Many of those will probably never be used at all, which I think is fine, but at least now you'll have one easy way to refer to all possible HTTP responses in one go!
Several subclasses add real behaviour on top of the status code, so they are
not just "a status number in a class". For example: 204 No Content and
205 Reset Content strip the Content-Type header and forbid setting a
response body; 201 Created requires a location and sets the Location
header; 405 Method Not Allowed requires the list of allowed methods and
sets the Allow header (as required by
RFC 9110); 503 Service
Unavailable accepts an optional retry_after keyword (seconds or a datetime)
and sets the Retry-After header. Using these classes keeps your responses
spec-compliant and consistent. Plus the explicit status names also help with
readability of your code!
One last benefit of using this module is that some HTTP status codes changed name in different RFCs. Django being a seasoned project is using the 'older' names for HTTP statuses. Our module uses newer names. For example, Django's HttpResponsePermanentRedirect returns a 302 by default but 302 is now "Found". Our HttpResponsePermanentRedirect returns 308, and we also include HttpResponseFound which returns 302 for when you might need it.
For the full API reference (all response classes and docstrings), see API Reference.