dj-webmachine Resource object methods
All dj-webmachine resources should inherit from the
webmachine.Resource class:
from webmachine import Resource
class MyResource(Resource):
""" my app resource """
Resource methods are of the signature:
def f(self, req, resp):
return result
req is a django.http.HttpRequest instance, and resp a
django.http.HttpResource instance. This instances have been
improved to support more HTTP semantics. At any time you
can manipulate this object to return the response you want or pass
values to other methods.
There are over 30 Resource methods you can define, but any of them can
be omitted as they have reasonable defaults.
Resource methods description
-
class webmachine.Resource
-
allow_missing_post(req, resp)
If the resource accepts POST requests to nonexistent resources,
then this should return True.
-
allowed_methods(req, resp)
If a Method not in this list is requested, then a
405 Method Not Allowed will be sent. Note that
these are all-caps and are string.
-
auth_required(req, resp)
-
-
charsets_provided(req, resp)
If this is anything other than None, it must be a list of pairs
where each pair is of the form Charset, Converter where Charset
is a string naming a charset and Converter is a callable function
in the resource which will be called on the produced body in a GET
and ensure that it is in Charset.
- Ex:
- return [(“iso-8859-1”, lambda x: x)]
Returning None prevents the character set negotiation
logic.
| Returns: | [(Charset, Handler)] |
|---|
-
content_types_accepted(req, resp)
This is used similarly to content_types_provided,
except that it is for incoming resource representations
– for example, PUT requests.
| Returns: | [(MediaType, Handler)] or None |
|---|
-
content_types_provided(req, resp)
This should return a list of pairs where each pair is of the form
(Mediatype, Handler) where Mediatype is a string of content-type
format and the Handler is an callable function which can provide
a resource representation in that media type. Content negotiation
is driven by this return value. For example, if a client request
includes an Accept header with a value that does not appear as a
first element in any of the return tuples, then a 406 Not Acceptable
will be sent.
| Returns: | [(MediaType, Handler)] or None |
|---|
-
created_location(req, resp)
-
-
delete_completed(req, resp)
This is only called after a successful delete_resource
call, and should return false if the deletion was accepted
but cannot yet be guaranteed to have finished.
-
delete_resource(req, resp)
This is called when a DELETE request should be enacted,
and should return true if the deletion succeeded.
-
encodings_provided(req, resp)
This must be a list of pairs where in each pair Encoding
is a string naming a valid content encoding and Encoder
is a callable function in the resource which will be
called on the produced body in a GET and ensure that it
is so encoded. One useful setting is to have the function
check on method, and on GET requests return [(“identity”, lambda x: x)]
as this is all that is needed to support identity encoding.
return [(“identity”, lambda x: x)]
Returning None prevents the encoding negotiation logic.
| Returns: | [(Encoding, Encoder)] |
|---|
-
expires(req, resp)
| Returns: | Nonr or Date string |
|---|
-
finish_request(req, resp)
This function, if defined, is called just before the final
response is constructed and sent. The Result is ignored, so
any effect of this function must be by returning a modified
request.
-
forbidden(req, resp)
-
-
format_suffix_accepted(req, resp)
Allows you to force the accepted format depending on path
suffix.
Ex: return [(“json”, “application/json”)]
will allows to force Accept header to application/json on
url /some/url.json
| Returns: | [(Suffix, MediaType)] or None |
|---|
-
generate_etag(req, resp)
If this returns a value, it will be used as the value of the ETag
header and for comparison in conditional requests.
-
get_urls()
method used to register utls in django urls routing.
-
is_authorized(req, resp)
If this returns anything other than true, the response will
be 401 Unauthorized. The AuthHead return value will be used
as the value in the WWW-Authenticate header.
-
is_conflict(req, resp)
If this returns true, the client will receive a 409 Conflict.
-
known_content_type(req, resp)
-
-
known_methods(req, resp)
-
-
languages_provided(req, resp)
return [“en”, “es”, “en-gb”]
returning None short circuits the language negotiation
-
last_modified(req, resp)
| Returns: | DateString or None |
|---|
-
malformed_request(req, resp)
-
-
moved_permanently(req, resp)
-
-
moved_temporarily(req, resp)
-
-
multiple_choices(req, resp)
If this returns true, then it is assumed that multiple
representations of the response are possible and a single
one cannot be automatically chosen, so a 300 Multiple Choices
will be sent instead of a 200.
-
options(req, resp)
If the OPTIONS method is supported and is used, the return
value of this function is expected to be a list of pairs
representing header names and values that should appear
in the response.
| Returns: | [(HeaderName, Value)] |
|---|
-
ping(req, resp)
-
-
post_is_create(req, resp)
If POST requests should be treated as a request to put content
into a (potentially new) resource as opposed to being a generic
submission for processing, then this function should return true.
If it does return true, then created_location will be called and the
rest of the request will be treated much like a PUT to the Path
entry returned by that call.
-
previously_existed(req, resp)
-
-
process_post(req, resp)
If post_is_create returns false, then this will be called to process
any POST requests. If it succeeds, it should return True.
-
resource_exists(req, resp)
Returning non-true values will result in 404 Not Found.
-
service_available(req, resp)
-
-
uri_too_long(req, resp)
-
-
-
valid_entity_length(req, resp)
-
-
variances(req, resp)
If this function is implemented, it should return a list
of strings with header names that should be included in
a given response’s Vary header. The standard conneg headers
(Accept, Accept-Encoding, Accept-Charset, Accept-Language)
do not need to be specified here as Webmachine will add the
correct elements of those automatically depending on resource
behavior.