djblets.webapi.resources.base¶
Base class for a resource in an API.
-
class
WebAPIResource
[source]¶ Bases:
object
A resource handling HTTP operations for part of the API.
A WebAPIResource is a RESTful resource living at a specific URL. It can represent either an object or a list of objects, and can respond to various HTTP methods (GET, POST, PUT, DELETE).
Subclasses are expected to override functions and variables in order to provide specific functionality, such as modifying the resource or creating a new resource.
For information on writing an API resource, see Writing Web API Resources.
-
allowed_mimetypes
= [{u'item': u'application/json', u'list': u'application/json'}, {u'item': u'application/xml', u'list': u'application/xml'}][source]¶
-
uri_name
[source]¶ Returns the name of the resource in the URI.
This can be overridden when the name in the URI needs to differ from the name used for the resource.
-
link_name
[source]¶ Returns the name of the resource for use in a link.
This can be overridden when the name in the link needs to differ from the name used for the resource.
-
call_method_view
(request, method, view, *args, **kwargs)[source]¶ Calls the given method view.
This will just call the given view by default, passing in all args and kwargs.
This can be overridden by subclasses to perform additional checks or pass additional data to the view.
-
get_object
(request, id_field=None, *args, **kwargs)[source]¶ Returns an object, given captured parameters from a URL.
This will perform a query for the object, taking into account
model_object_key
,uri_object_key
, and any captured parameters from the URL.This requires that
model
anduri_object_key
be set.Throws django.core.exceptions.ObjectDoesNotExist if the requested object does not exist.
-
post
(*args, **kwargs)[source]¶ Handles HTTP POSTs.
This is not meant to be overridden unless there are specific needs.
This will invoke
create
if doing an HTTP POST on a list resource.By default, an HTTP POST is not allowed on individual object resourcces.
-
put
(request, *args, **kwargs)[source]¶ Handles HTTP PUTs.
This is not meant to be overridden unless there are specific needs.
This will just invoke
update
.
-
get
(**kwargs)[source]¶ Handles HTTP GETs to individual object resources.
By default, this will check for access permissions and query for the object. It will then return a serialized form of the object.
This may need to be overridden if needing more complex logic.
-
get_list
(**kwargs)[source]¶ Handles HTTP GETs to list resources.
By default, this will query for a list of objects and return the list in a serialized form.
-
create
(**kwargs)[source]¶ Handles HTTP POST requests to list resources.
This is used to create a new object on the list, given the data provided in the request. It should usually return HTTP 201 Created upon success.
By default, this returns HTTP 405 Method Not Allowed.
-
update
(**kwargs)[source]¶ Handles HTTP PUT requests to object resources.
This is used to update an object, given full or partial data provided in the request. It should usually return HTTP 200 OK upon success.
By default, this returns HTTP 405 Method Not Allowed.
-
delete
(**kwargs)[source]¶ Handles HTTP DELETE requests to object resources.
This is used to delete an object, if the user has permissions to do so.
By default, this deletes the object and returns HTTP 204 No Content.
-
get_queryset
(request, is_list=False, *args, **kwargs)[source]¶ Returns a queryset used for querying objects or lists of objects.
Throws django.core.exceptions.ObjectDoesNotExist if the requested object does not exist.
This can be overridden to filter the object list, such as for hiding non-public objects.
The
is_list
parameter can be used to specialize the query based on whether an individual object or a list of objects is being queried.
-
get_url_patterns
()[source]¶ Returns the Django URL patterns for this object and its children.
This is used to automatically build up the URL hierarchy for all objects. Projects should call this for top-level resources and return them in the
urls.py
files.
-
has_access_permissions
(request, obj, *args, **kwargs)[source]¶ Returns whether or not the user has read access to this object.
-
has_list_access_permissions
(request, *args, **kwargs)[source]¶ Returns whether or not the user has read access to this list.
-
has_modify_permissions
(request, obj, *args, **kwargs)[source]¶ Returns whether or not the user can modify this object.
-
has_delete_permissions
(request, obj, *args, **kwargs)[source]¶ Returns whether or not the user can delete this object.
-
serialize_link
(obj, *args, **kwargs)[source]¶ Serialize a link to the object into a Python dictionary.
-
get_object_title
(obj, request=None, *args, **kwargs)[source]¶ Return the object’s title.
By default, this returns the object’s unicode representation.
Parameters: - obj (object) – The object to serialize.
- request (django.http.HttpRequest) – The current request.
- *args (tuple) – Additional positional arguments.
- **kwargs (dict) – Additional keyword arguments.
Returns: The object’s title.
Return type: unicode
-
get_only_fields
(request)[source]¶ Returns the list of the only fields that the payload should include.
If the user has requested that no fields should be provided, this will return an empty list.
If all fields will be included in the payload, this will return None.
-
get_only_links
(request)[source]¶ Returns the list of the only links that the payload should include.
If the user has requested that no links should be provided, this will return an empty list.
If all links will be included in the payload, this will return None.
-
get_serializer_for_object
(obj)[source]¶ Returns the serializer used to serialize an object.
This is called when serializing objects for payloads returned by this resource instance. It must return the resource instance that will be responsible for serializing the given object for the payload.
By default, this calls
get_resource_for_object
to find the appropriate resource.
-
get_links
(resources=[], obj=None, request=None, *args, **kwargs)[source]¶ Returns a dictionary of links coming off this resource.
The resulting links will point to the resources passed in
resources
, and will also provide special resources forself
(which points back to the official location for this resource) and one per HTTP method/operation allowed on this resource.
Returns links related to this resource.
The result should be a dictionary of link names to a dictionary of information. The information should contain:
- ‘method’ - The HTTP method
- ‘href’ - The URL
- ‘title’ - The title of the link (optional)
- ‘resource’ - The WebAPIResource instance
- ‘list-resource’ - True if this links to a list resource (optional)
-
get_list_url
(**kwargs)[source]¶ Return the URL to the list version of this resource.
This will generate a URL for the list resource, given the provided arguments for the URL pattern.
Parameters: kwargs (dict) – The keyword arguments needed for URL resolution. Returns: The resulting absolute URL to the list resource. Return type: unicode
-
get_item_url
(**kwargs)[source]¶ Return the URL to the item version of this resource.
This will generate a URL for the item resource, given the provided arguments for the URL pattern.
Parameters: kwargs (dict) – The keyword arguments needed for URL resolution. Returns: The resulting absolute URL to the item resource. Return type: unicode
-
build_resource_url
(name, request=None, **kwargs)[source]¶ Build a resource URL for the given name and keyword arguments.
This can be overridden by subclasses that have special requirements for URL resolution.
Parameters: - name (unicode) – The name of the resource.
- request (HttpRequest) – The HTTP request from the client.
- kwargs (dict) – The keyword arguments needed for URL resolution.
Returns: The resulting absolute URL to the resource.
Return type: unicode
-
get_href_parent_ids
(obj, **kwargs)[source]¶ Returns a dictionary mapping parent object keys to their values for an object.
-
get_parent_object
(obj)[source]¶ Returns the parent of an object.
By default, this uses
model_parent_key
to figure out the parent, but it can be overridden for more complex behavior.
-
get_last_modified
(request, obj)[source]¶ Returns the last modified timestamp of an object.
By default, this uses
last_modified_field
to determine what field in the model represents the last modified timestamp of the object.This can be overridden for more complex behavior.
-
get_etag
(request, obj, *args, **kwargs)[source]¶ Returns the ETag representing the state of the object.
By default, this uses
etag_field
to determine what field in the model is unique enough to represent the state of the object.This can be overridden for more complex behavior. Any overridden functions should make sure to pass the result through
encode_etag
before returning a value.
-
encode_etag
(request, etag, *args, **kwargs)[source]¶ Encodes an ETag for usage in a header.
This will take a precomputed ETag, augment it with additional information, encode it as a SHA1, and return it.
-
generate_etag
(obj, fields, request, encode_etag=True, **kwargs)[source]¶ Generate an ETag from the serialized values of all given fields.
Deprecated since version 2.0: This method is no longer called internally, as the auto-generation logic for ETags has changed. It’s left here for any resources that may still call it, and is scheduled to be removed in a future release.
Parameters: - obj (object) – The object being serialized.
- fields (list of unicode, unused) – An unused list of field names. You can provide any value here. It will be ignored.
- request (django.http.HttpRequest) – The HTTP request from the client.
- encode_etag (bool, optional) – Whether to encode the ETag to a SHA.
- **kwargs (dict) – Extra keyword arguments for
serialize_object()
.
Returns: The generated ETag.
Return type: unicode
-
are_cache_headers_current
(request, last_modified=None, etag=None)[source]¶ Determines if cache headers from the client are current.
This will compare the optionally-provided timestamp and ETag against any conditional cache headers sent by the client to determine if the headers are current. If they are, the caller can return HttpResponseNotModified instead of a payload.
-