HTTP Utilities

In nap.http is a set of tools to go one step further than Django’s existing HttpResponse.

Status

Firstly, there is STATUS_CODES, which is a list of two-tuples of HTTP Status codes and their descriptions.

Also, and more usefully, there is the STATUS object. Accessing it as a dict, you can look up HTTP status code descriptions by code:

>>> STATUS[401]
'Unauthorized'

However, you can also look up attributes to find out the status code:

>>> STATUS.UNAUTHORIZED
401

This lets it act as a two-way constant.

BaseHttpResponse

This class blends Django’s HttpResponse with Python’s Exception. Why? Because then, when you’re nested who-knows how deep in your code, it can raise a response, instead of having to return one and hope everyone bubbles it all the way up.

  • BaseHttpResponse

    • HttpResponseSuccess

      • OK
      • Created
      • Accepted
      • NoContent
      • ResetContent
      • PartialContent

    • HttpResponseRedirect

      • MultipleChoices
      • MovedPermanently*
      • Found*
      • SeeOther*
      • NotModified
      • UseProxy*
      • TemporaryRedirect
      • PermanentRedirect

      Items marked with a * require a location passed as their first argument. It will be set as the Location header in the response.

    • HttpResponseError

      A common base class for all Error responses (4xx and 5xx)

    • HttpResponseClientError(HttpResponseError)

      • BadRequest
      • Unauthorized
      • PaymentRequired
      • Forbidden
      • NotFound
      • MethodNotAllowed
      • NotAcceptable
      • ProxyAuthenticationRequired
      • RequestTimeout
      • Conflict
      • Gone
      • LengthRequired
      • PreconditionFailed
      • RequestEntityTooLarge
      • RequestURITooLong
      • UnsupportedMediaType
      • RequestedRangeNotSatisfiable
      • ExpectationFailed

    • HttpResponseServerError(HttpResponseError)

      • InternalServerError
      • NotImplemented
      • BadGateway
      • ServiceUnavailable
      • GatewayTimeout
      • HttpVersiontNotSupported

It will be clear that, unlike Django, these mostly do not start with HttpResponse. This is a personal preference, in that typically you’d use:

from nap import http

...
    return http.Accept(...)

except_response

In case you want to use these raiseable responses in your own views, Nap provides a except_response decorator.

from nap.http.decorators import except_response

@except_response
def myview(request):
    try:
        obj = Thing.objects.get(user=request.user)
    except:
        raise http.BadRequest()
    return render(...)

The decorator will catch any http.BaseHttpResponse exceptions and return them as the views response.

Http404 versus http.NotFound

Generally in your API, you’ll want to prefer http.NotFound for returning a 404 response. This avoids being caught by the normal 404 handling, so it won’t invoke your handler404.