Defines a RESTful resource.
Users are expected to subclass this object & implement a handful of methods:
Additionally, the user may choose to implement:
Users may also wish to define a fields attribute on the class. By providing a dictionary of output names mapped to a dotted lookup path, you can control the serialized output.
Users may also choose to override the status_map and/or http_methods on the class. These respectively control the HTTP status codes returned by the views and the way views are looked up (based on HTTP method & endpoint).
Used for hooking up the actual detail-style endpoints, this returns a wrapper function that creates a new instance of the resource class & calls the correct view method for it.
Parameters: |
|
---|---|
Returns: | View function |
Used for hooking up the actual list-style endpoints, this returns a wrapper function that creates a new instance of the resource class & calls the correct view method for it.
Parameters: |
|
---|---|
Returns: | View function |
When an exception is encountered, this generates a JSON error message for display to the user.
Parameters: | err (Exception) – The exception seen. The message is exposed to the user, so beware of sensitive data leaking. |
---|---|
Returns: | A response object |
Given some data, generates an HTTP response.
The default implementation is Django-specific, so if you’re integrating with a new web framework, you’ll need to override this method within your subclass.
Parameters: |
|
---|---|
Returns: | A response object |
Allows for creating data via a POST on a list-style endpoint.
MUST BE OVERRIDDEN BY THE USER - By default, this returns MethodNotImplemented.
Returns: | May return the created item or None |
---|
Creates a subcollection of data for a POST on a detail-style endpoint.
Uncommonly implemented due to the rarity of having nested collections.
MUST BE OVERRIDDEN BY THE USER - By default, this returns MethodNotImplemented.
Returns: | A collection of data |
---|---|
Return type: | list or iterable |
Deletes data for a DELETE on a detail-style endpoint.
MUST BE OVERRIDDEN BY THE USER - By default, this returns MethodNotImplemented.
Returns: | None |
---|
Deletes ALL data in the collection for a DELETE on a list-style endpoint.
Uncommonly implemented due to potential of trashing large datasets. Implement with care.
MUST BE OVERRIDDEN BY THE USER - By default, this returns MethodNotImplemented.
Returns: | None |
---|
A convenience method for deserializing the body of a request.
If called on a list-style endpoint, this calls deserialize_list. Otherwise, it will call deserialize_detail.
Parameters: |
|
---|---|
Returns: | The deserialized data |
Return type: | list or dict |
Given a string of text, deserializes a (presumed) object out of the body.
Parameters: | body (string) – The body of the current request |
---|---|
Returns: | The deserialized body or an empty dict |
Given a string of text, deserializes a (presumed) list out of the body.
Parameters: | body (string) – The body of the current request |
---|---|
Returns: | The deserialized body or an empty list |
Returns the data for a GET on a detail-style endpoint.
MUST BE OVERRIDDEN BY THE USER - By default, this returns MethodNotImplemented.
Returns: | An item |
---|---|
Return type: | object or dict |
A convenient dispatching method, this centralized some of the common flow of the views.
This wraps/calls the methods the user defines (list/detail/create etc.), allowing the user to ignore the authentication/deserialization/serialization/response & just focus on their data/interactions.
Parameters: |
|
---|---|
Returns: | A response object |
A simple hook method for controlling whether a request is authenticated to continue.
By default, we only allow the safe GET methods. All others are denied.
Returns: | Whether the request is authenticated or not. |
---|---|
Return type: | boolean |
Controls whether or not the resource is in a debug environment.
If so, exceptions will be reraised instead of returning a serialized response.
The default implementation simply returns False, so if you’re integrating with a new web framework, you’ll need to override this method within your subclass.
Returns: | If the resource is in a debug environment |
---|---|
Return type: | boolean |
Returns the data for a GET on a list-style endpoint.
MUST BE OVERRIDDEN BY THE USER - By default, this returns MethodNotImplemented.
Returns: | A collection of data |
---|---|
Return type: | list or iterable |
Given an item (object or dict), this will potentially go through & reshape the output based on self.fields.
If self.fields is empty or None, the entire thing will be returned.
If self.fields is present/populated, this will use the lookup to extract data & shape the resulting output match the keys of self.fields.
Parameters: | data (object or dict) – An item to prepare for serialization |
---|---|
Returns: | A potentially reshaped dict |
Return type: | dict |
The low-level deserialization.
Underpins deserialize, deserialize_list & deserialize_detail.
Has no built-in smarts, simply loads the JSON.
Parameters: | body (string) – The body of the current request |
---|---|
Returns: | The deserialized data |
Return type: | list or dict |
The low-level serialization.
Underpins serialize, serialize_list & serialize_detail.
Has no built-in smarts, simply dumps the JSON.
Parameters: | data (string) – The body for the response |
---|---|
Returns: | A serialized version of the data |
Return type: | string |
Returns the body of the current request.
Useful for deserializing the content the user sent (typically JSON).
The default implementation is Django-specific, so if you’re integrating with a new web framework, you’ll need to override this method within your subclass.
Returns: | The body of the request |
---|---|
Return type: | string |
Returns the HTTP method for the current request.
The default implementation is Django-specific, so if you’re integrating with a new web framework, you’ll need to override this method within your subclass.
Returns: | The HTTP method in uppercase |
---|---|
Return type: | string |
A convenience method for serializing data for a response.
If called on a list-style endpoint, this calls serialize_list. Otherwise, it will call serialize_detail.
Parameters: |
|
---|---|
Returns: | A serialized version of the data |
Return type: | string |
Given a single item (object or dict), serializes it.
This will call prepare on the item, to optionally reshape the output.
Parameters: | data (object or dict) – The item to serialize |
---|---|
Returns: | The serialized body |
Return type: | string |
Given a collection of data (objects or dicts), serializes them.
This will call prepare for each item, to optionally reshape the output.
Parameters: | data (list or iterable) – The collection of items to serialize |
---|---|
Returns: | The serialized body |
Return type: | string |
Updates existing data for a PUT on a detail-style endpoint.
MUST BE OVERRIDDEN BY THE USER - By default, this returns MethodNotImplemented.
Returns: | May return the updated item or None |
---|
Updates the entire collection for a PUT on a list-style endpoint.
Uncommonly implemented due to the complexity & (varying) busines-logic involved.
MUST BE OVERRIDDEN BY THE USER - By default, this returns MethodNotImplemented.
Returns: | A collection of data |
---|---|
Return type: | list or iterable |
Takes a list of data & wraps it in a dictionary (within the objects key).
For security in JSON responses, it’s better to wrap the list results in an object (due to the way the Array constructor can be attacked in Javascript). See http://haacked.com/archive/2009/06/25/json-hijacking.aspx/ & similar for details.
Overridable to allow for modifying the key names, adding data (or just insecurely return a plain old list if that’s your thing).
Parameters: | data (list) – A list of data about to be serialized |
---|---|
Returns: | A wrapping dict |
Return type: | dict |
A Django-specific Resource subclass.
Doesn’t require any special configuration, but helps when working in a Django environment.
A convenience method for hooking up the URLs.
This automatically adds a list & a detail endpoint to your URLconf.
Parameters: | name_prefix (string) – (Optional) A prefix for the URL’s name (for resolving). The default is None, which will autocreate a prefix based on the class name. Ex: BlogPostResource -> api_blog_post_list |
---|---|
Returns: | A patterns object for include(...) |
A Flask-specific Resource subclass.
Doesn’t require any special configuration, but helps when working in a Flask environment.
A convenience method for hooking up the URLs.
This automatically adds a list & a detail endpoint to your routes.
Parameters: |
|
---|---|
Returns: | Nothing |
A Pyramid-specific Resource subclass.
Doesn’t require any special configuration, but helps when working in a Pyramid environment.