djblets.webapi.resources.root¶

A flexible resource for the root of your API resource tree.

URITemplates¶

A type alias for a mapping of URI templates.

Each key is a URI template name, and each value is a URL.

New in version 3.2.

alias of Dict[str, str]

class RootResource(child_resources=[], include_uri_templates=True)¶

Bases: WebAPIResource

The root of a resource tree.

This is meant to be instantiated with a list of immediate child resources. The result of get_url_patterns() should be included in a project’s urls.py.

name = 'root'¶

singleton = True¶

class ResourceEntry(name, list_href, resource, is_list, uri_template_name)¶

Bases: tuple

Whether or not the resource is a list resource.

uri_template_name (str): The name of the resource to use in the URI templates list.

__getnewargs__()¶: Return self as a plain tuple. Used by copy and pickle.

static __new__(_cls, name, list_href, resource, is_list, uri_template_name)¶: Create new instance of ResourceEntry(name, list_href, resource, is_list, uri_template_name)

__repr__()¶: Return a nicely formatted representation string

__slots__ = ()¶

is_list¶: Alias for field number 3

list_href¶: Alias for field number 1

name¶: Alias for field number 0

resource¶: Alias for field number 2

uri_template_name¶: Alias for field number 4

__init__(child_resources=[], include_uri_templates=True)¶

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.

get(request, *args, **kwargs)¶: Retrieve the list of top-level resources and URL templates.

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

Serialize the contents of the root resource.

By default, this just provides links and URI templates. Subclasses can override this to provide additional data, or to otherwise change the structure of the root resource.

get_uri_templates(request: HttpRequest, *args, **kwargs) → Dict[str, str]¶

Return all URI templates in the resource tree.

REST APIs can be very chatty if a client wants to be well-behaved and crawl the resource tree asking for the links, instead of hard-coding the paths. The benefit is that they can keep from breaking when paths change. The downside is that it can take many HTTP requests to get the right resource.

This list of all URI templates allows clients who know the resource name and the data they care about to simply plug them into the URI template instead of trying to crawl over the whole tree. This can make things far more efficient.

Parameters:

request (django.http.HttpRequest) – The GET request for the Root resource.
*args (tuple, unused) – Additional unused arguments.
**kwargs (dict, unused) – Additional unused keyword arguments.

Returns:

A mapping of resources to their URI templates.

Return type:

dict

build_uri_templates(base_href: str) → Dict[str, str]¶

Build the URI templates to include in the payload.

The resource will cache these automatically in local memory, so that repeated calls will often be unnecessary. This allows for things like per-organization APIs that each have their own cache.

Caches are automatically invalidated as needed.

New in version 3.2.

Parameters:: base_href (str) – The base URL for the API endpoint.
Returns:: A dictionary mapping URI template keys to template values.
Return type:: dict

classmethod walk_resources(resource, list_href)¶

Yield all URI endpoints associated with a specified resource.

Parameters:

djblets.webapi.resources.WebAPIResource (resource) – The starting point for searching the resource tree.
list_href (unicode) – The path to the list resource, relative to the WebAPIResource provided. Used as a component of the URL in the API.

Yields:

RootResource.ResourceEntry – Resource entries for all sub-resources.

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

Default handler at the end of the URL patterns.

This returns an API 404, instead of a normal django 404.

get_url_patterns()¶

Return the Django URL patterns for this object and its children.

This returns the same list as WebAPIResource.get_url_patterns(), but also introduces a generic catch-all 404 handler which returns API errors instead of HTML.

register_uri_template(name: str, relative_path: str, relative_resource: Optional[WebAPIResource] = None) → None¶

This adds the specified name and relative resource to the Root Resource’s URI templates.

Parameters:

name (str) – The name of the associated resource being added to templates.
relative_path (str) – The path of the API resource relative to its parent resources.
relative_resource (djblets.webapi.resources.base.WebAPIResource, optional) – The resource instance associated with this URI template.

unregister_uri_template(name: str, relative_resource: Optional[WebAPIResource] = None) → None¶

Unregister the specified resource for URI template serialization.

This removes the specified name and relative resource to the Root Resource’s URI templates.

Parameters:

name (str) – The name of the resource being removed from templates.
relative_resource (djblets.webapi.resources.base.WebAPIResource, optional) – The resource instance associated with this URI template.