djblets.webapi.resources.base¶

Base class for a resource in an API.

class WebAPIResource¶

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.

model = None¶

fields = {}¶

uri_object_key_regex = '[0-9]+'¶

uri_object_key = None¶

model_object_key = 'pk'¶

model_parent_key = None¶

last_modified_field = None¶

etag_field = None¶

autogenerate_etags = False¶

singleton = False¶

list_child_resources = []¶

item_child_resources = []¶

allowed_methods = ('GET',)¶

mimetype_vendor = None¶

mimetype_list_resource_name = None¶

mimetype_item_resource_name = None¶

paginated_cls¶

The class to use for paginated results in get_list.

alias of WebAPIResponsePaginated

method_mapping = {'DELETE': 'delete', 'GET': 'get', 'POST': 'post', 'PUT': 'put'}¶

__init__()¶

allowed_mimetypes = [{'list': 'application/json', 'item': 'application/json'}, {'list': 'application/xml', 'item': 'application/xml'}]¶

__call__(request, api_format=None, *args, **kwargs)¶

Invokes the correct HTTP handler based on the type of request.

__name__ = 'WebAPIResource'¶

property name¶

Returns the name of the object, used for keys in the payloads.

property name_plural¶

Returns the plural name of the object, used for lists.

property item_result_key¶

Returns the key for single objects in the payload.

property list_result_key¶

Returns the key for lists of objects in the payload.

property uri_name¶

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.

property link_name¶

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.

uri_template_name()¶

Returns the name of the resource for use in URI templates.

This will be used as the key for this resource in :py:class`djblets.webapi.resource.root.RootResource`’s list of URI templates. This can be overridden when the URI template name for this resource needs to differ from the name used for the resource.

This must be unique to the resource. If set to None this resource will be excluded from the URI templates list.

New in version 3.1.0.

Type:

str or None

uri_template_name_plural()¶

Returns the plural name of the resource for use in URI templates.

This will be used as the key for the list version of this resource in :py:class`djblets.webapi.resource.root.RootResource`’s list of URI templates. This can be overridden when the URI template name for this resource needs to differ from the name used for the resource.

This must be unique to the resource. If set to None the list version of this resource will be excluded from the URI templates list.

New in version 3.1.0.

Type:

str or None

call_method_view(request, method, view, *args, **kwargs)¶

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.

build_response_args(request)¶

get_object(request, id_field=None, *args, **kwargs)¶

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 and uri_object_key be set.

Throws django.core.exceptions.ObjectDoesNotExist if the requested object does not exist.

post(*args, **kwargs)¶

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)¶

Handles HTTP PUTs.

This is not meant to be overridden unless there are specific needs.

This will just invoke update.

get(**kwargs)¶

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)¶

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)¶

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)¶

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)¶

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)¶

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()¶

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)¶

Returns whether or not the user has read access to this object.

has_list_access_permissions(request, *args, **kwargs)¶

Returns whether or not the user has read access to this list.

has_modify_permissions(request, obj, *args, **kwargs)¶

Returns whether or not the user can modify this object.

has_delete_permissions(request, obj, *args, **kwargs)¶

Returns whether or not the user can delete this object.

get_link_serializer(field)¶

Return the function to use for serializing a link field.

serialize_link(obj, *args, **kwargs)¶

Serialize a link to the object into a Python dictionary.

get_object_title(obj, request=None, *args, **kwargs)¶

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

serialize_object(obj, *args, **kwargs)¶

Serializes the object into a Python dictionary.

get_only_fields(request)¶

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)¶

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)¶

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)¶

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 for self (which points back to the official location for this resource) and one per HTTP method/operation allowed on this resource.

get_related_links(obj=None, request=None, *args, **kwargs)¶

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_href(obj, request, *args, **kwargs)¶

Returns the URL for this object.

get_list_url(**kwargs)¶

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)¶

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)¶

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)¶

Returns a dictionary mapping parent object keys to their values for an object.

get_parent_object(obj)¶

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)¶

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)¶

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)¶

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.

are_cache_headers_current(request, last_modified=None, etag=None)¶

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.

get_no_access_error(request, *args, **kwargs)¶

Returns an appropriate error when access is denied.

By default, this will return PERMISSION_DENIED if the user is logged in, and NOT_LOGGED_IN if the user is anonymous.

Subclasses can override this to return different or more detailed errors.