Tastypie Module: tastypie/lib/resource

Provides the base resource for defining expressive APIs, handling serialization, deserialization, validation,
caching, throttling and error handling

new (require("tastypie/lib/resource"))( [options])

The base resource implementation providing hooks for extension

Parameters:

Name Type Argument Description

options

Object

Options data configuration

Properties

Name Type Argument Default Description

name

String

null

The primary mount path for the resource /, //{pk}. This will be set by the Api instance if not set

pk

String

The field name to use as the unique identifier for each entity

includeUri

Boolean

true

If set to true, a field named uri will be added to the resource instance

callbackKey

string

callback

callback key to be used for jsonp responsed

defaultFormat

string

'application/json'

the default serialziion format if one is not specified

serializer

module:tastypie/lib/serializer

serializer

an instance of a serializer to be used to translate data objects

routes

Array.<Object>

null

An array of route definitions add to the resources default crud routes

collection

String

data

the name of the key to be used lists of objects on list endpoints

labelField

String

data

A field to be included in minimal responses

limit

Number

The maximum number of results to return per page for the list endpoint

paginator

module:tastypie/lib/paginator

paginator

a Paginator Class used to page large list

cache

Object

A cache instance to be used for response caching.

Properties

Name	Type	Argument	Default	Description
`engine`	Object	<optional>	'catbox-noop'	The underlying engine type to use. This should be a requireable catbox module that is installed

allowed

Object

an object which maps HTTP method names to a boolean {get:true} This is used as a default for custom actions if non is defined

Properties

Name	Type	Argument	Description
`methods`	Object	<optional>	an object which maps HTTP method names to a boolean {get:true} This is used as a default for custom actions if non is defined
`list`	Object	<optional>	Defines methods access for listing methods. Defaults to the definitions found in the methods object if not defined
`detail`	Object	<optional>	Defines methods access for detail methods. Defaults to the definitions found in the methods object if not defined

returnData

Boolean

true

return data after put, post requests.

filtering

Object

null

And object defining an array of allowable filter types for each field

Mixes In:

Source:

lib/resource/index.js

Tutorials:

Working With Resources

Example

vaar Resource = require('tastypie').Resource
var instnace = new Resource({
    limit:10,
    pk:'user_id',
    defaultFormat:'text/xml',
    collection:'users'
    allowed:{
        list:{
            get:true,
            put:false,
            post:false
            delete:false
        },
        detail:{
            get:true,
            put:true,
            post:false
        }
    }
})

Requires

module:class
module:class/options
module:domain
module:events
module:util
module:async
module:url-join
module:joi
module:boom
module:querystring
module:mout/lang
module:mout/string/interpolate
module:debug
module:tastypie/lib/class
module:tastypie/lib/class/parent
module:tastypie/lib/class/options
module:tastypie/lib/http
module:tastypie/lib/mime
module:tastypie/lib/utility
module:tastypie/lib/paginator
module:tastypie/lib/exceptions
module:tastypie/lib/cache
module:tastypie/lib/throttle
module:tastypie/lib/fields
module:tastypie/lib/resource/detail
module:tastypie/lib/resource/list
module:tastypie/lib/resource/schema
module:tastypie/lib/resource/validator

Methods

<static> extend(proto)

Helper method to subclass the base resource

Parameters:

Name	Type	Description
`proto`	Object	An object to use as the prototyp of a new resource type

Source:

lib/resource/index.js

Returns:

Type: module:tastypie/lib/resource

base_urls()

Defines the base urls for this resource

Source:

lib/resource/index.js

Returns:

Array. And array of objects containing a route, name and handler propperty

Example

{
    base_urls: fuinction(){
        return [{
            path:decodeURIComponent('/api/v1/test/{action}'),
            name:"test",
            handler: this.dispatch_test.bind( this )
        }];
    }
}

build_schema()

function used to generate a resource schema

Source:

lib/resource/schema.js

Returns:

schema

Type: Object

buildFilters(fiters)

creates an object to be used to filter data before it is returns.
NOTE this needs to be implemented to suit the the data source backend

Parameters:

Name	Type	Description
`fiters`	Object	An object of requested filters

Source:

lib/resource/index.js

Returns:

filters An object of filter definitions suitable to be pased to the data backend

Type: Object

bundle(req, res [, data] [, obj])

Packages peices of the request in a single object for easy passing

Parameters:

Name	Type	Argument	Default	Description
`req`	Request			A Hapijs request object request object
`res`	Response			A Hapijs reply object
`data`	Object	<optional>	{}	The data object to package
`obj`	Object	<optional>		and object instance used for hydration

Source:

lib/resource/index.js

Returns:

Object An object packaging important information about the current request

<protected> cacheKey(type, uri, method, resource, query, params)

function used to generate a unique cache key

Parameters:

Name	Type	Description
`type`	String
`uri`	String
`method`	String
`resource`	String
`query`	Object
`params`	Object

Source:

lib/resource/index.js

Returns:

key A valid cache key for the current request

Type: String

<protected> check(action, bundle)

Executes a given check against a request bundle
action checks can be verb, dispatch, access

Parameters:

Name	Type	Description
`action`	String	The http action to check
`bundle`	module:tastypie/lib/resource~Bundle	a request bundle

Source:

lib/resource/index.js

Returns:

Type: Mixed

<protected> create_object(bundle, callback)

Internal method used during the post_list method

Parameters:

Name	Type	Description
`bundle`	Bundle	A bundle representing the current request
`callback`	module:tastypie/lib/resource~Nodeback	a callback function to call when the operation is complete

Source:

lib/resource/list.js

dehydrate(obj)

A final hook to run and last deydration operations before a response is returned

Parameters:

Name	Type	Description
`obj`	Object	An object to dehydrate

Source:

lib/resource/index.js

Returns:

Type: Object

dehydrate_uri(obj, bundle, result)

Generates a uri for a specific object related to this resource

Parameters:

Name	Type	Description
`obj`	Object
`bundle`	Bundle
`result`	Objectd

Source:

lib/resource/index.js

Returns:

uri

Type: String

deserialize(data, format, callback)

converts a data string into an object

Parameters:

Name	Type	Description
`data`	String	A string of data to be parsed
`format`	String	the content type ( application/json, text/xml, etc ) of the in coming data string
`callback`	module:tastypie/lib/resource~Nodeback

Source:

lib/resource/index.js

dispatch(action, bundle)

Primary entry point for a request into the resource. maps Http methods to resource methods

Parameters:

Name	Type	Description
`action`	String	the resource action to route the request to
`bundle`	Object \| Bundle	A bundle representing the current request

Source:

lib/resource/index.js

dispatch_detail(req, rep, next)

Dispatches detail requests which operated on a sigular, specific object

Parameters:

Name	Type	Description
`req`	Request	An express request object
`rep`	Response	An express response object
`next`	function	An express next callback

Source:

lib/resource/detail.js

exception(Error)

Used to handle uncaught caugt errors during the request life cycle.

Parameters:

Name	Type	Description
`Error`	RequestError	The error generated during the request

Source:

lib/resource/index.js

filter(bundle, filters)

Applies custom filtering to a given set of objects.

Parameters:

Name	Type	Description
`bundle`	Bundle	A request bundle
`filters`	Object	An implementation specific object used to filter data sets

Source:

lib/resource/index.js

Returns:

Type: Object

format(bundle [, types])

Attempts to determine the best serialization format for a given request

Parameters:

Name	Type	Argument	Description
`bundle`	Bundle \| Object		A bundle object or similar object
`types`	Array	<optional>	An array of possible content types this resource can deal with.

Source:

lib/resource/index.js

Returns:

accepts an accepted format for the the related request

Type: String

<protected> from_cache(type, bundle, callback)

reads a valeue from the specified cache backend by name. If nothing is found in
cache it wil call get_object

Parameters:

Name	Type	Description
`type`	String	of request ( list, detail, updload, etc)
`bundle`	Bundle	A bundle representing the current request
`callback`	function	A calback function to use whkf

Source:

lib/resource/index.js

full_dehydrate(obj)

A hook before serialization to converte and complex objects or classes into simple serializable objects

Parameters:

Name	Type	Description
`obj`	Object	an object to dehydrate object

Source:

lib/resource/index.js

Returns:

Object An object containing only serializable data

full_hydrate(bundle)

Responsible for converting a raw data object into a resource mapped object

Parameters:

Name	Type	Description
`bundle`	Bundle

Source:

lib/resource/index.js

Returns:

Type: Bundle

get_detail(bundle)

Top level method used to retreive indiidual objects by id.
This method handles caching results as well as reading from the cache

Parameters:

Name	Type	Description
`bundle`	Bundle	A bundle representing the current request.

Source:

lib/resource/detail.js

get_list(bundle)

Top level function used to handle get requests for listing endpoints. It handles paging and serialization

Parameters:

Name	Type	Description
`bundle`	Bundle	A bundle representing the current request

Source:

lib/resource/list.js

get_object(bundle, callback)

Method used to retrieve a specific object
NOTE This method must be implement for specific use cases. The default does not implement this method

Parameters:

Name	Type	Description
`bundle`	module:tastypie/lib/resource~Bundle
`callback`	module:tastypie/lib/resource~Nodeback

Source:

lib/resource/detail.js

Examples

var MyResource = Resource.extend({
  get_object: function( bundle, callback ){
    Model.get( bundle.req.params.pk, callback )
  }
})

var MyResource = new Class({
  inherits: Resource
  , get_object: function( bundle, callback ){
    this.get_objects(bundle,function(e, objects){
      var obj = JSON.parse( objects ).filter(function( obj ){
        return obj._id = bundle.req.params.pk
      })[0]
      callback( null, obj )
    })
  }
})

get_objects(bundle, callback)

Internal method used to retrieve a full list of objects for a resource

Parameters:

Name	Type	Description
`bundle`	module:tastypie/lib/resource~Bundle
`callback`	module:tastypie/lib/resource~Nodeback	callback function to call when data retrieval is

Source:

lib/resource/list.js

get_schema(request, reply)

Top level method for generating resource specific schemas for GET requests

Parameters:

Name	Type	Description
`request`	Request	A Hapi.js request object
`reply`	function	A hapi.js reply function

Source:

lib/resource/schema.js

hydrate(bundle)

Final hydration hook method. Is a noop by default

Parameters:

Name	Type	Description
`bundle`	Bundle

Source:

lib/resource/index.js

Returns:

Type: Bundle

pk(orig, bundle, result)

Attempts to determine the primary key value of the specific object related to a resource request

Parameters:

Name	Type	Description
`orig`	Object
`bundle`	Bundle
`result`	Object

Source:

lib/resource/index.js

Returns:

pk The value at the configured primary key field of the object related to the resource

Type: String | Number

post_list(bundle)

Top level method used to handle post request to listing endpoints. Used to create new instances
of the associated resource

Parameters:

Name	Type	Description
`bundle`	Bundle	An object represneting the current `POST` request

Source:

lib/resource/list.js

prepend_urls()

A method which returns additaional urls to be added to the default uri defintion of a resource

Source:

lib/resource/index.js

Returns:

Array an empty array

put_detail(bundle)

Top level method used to handle post request to listing endpoints. Used to update instances with supplied data

Parameters:

Name	Type	Description
`bundle`	module:tastypie/lib/resource~Bundle	An object represneting the current `PUT` request

Source:

lib/resource/detail.js

replace_object(bundle, callback)

Low level function called to replace existing objects

Parameters:

Name	Type	Description
`bundle`	module:tastypie/lib/resource~Bundle	An object represneting the current `PUT` request
`callback`	module:tastypie/lib/resource~NodeBack	a callback to be caled when finished

Source:

lib/resource/detail.js

respond(bundle, cls)

Method to generate a response for a bundled request. Will set contnent-type and length headers

Parameters:

Name	Type	Description
`bundle`	Bundle \| Object	A bundle or similar object
`cls`	HttpResponse \| function	An HttpResponse function to call to finish the request. Function should accept a response object, and data to send

Source:

lib/resource/index.js

Returns:

Resource

serialize(data, format, callback)

Converts a valid object in to a string of the specified format

Parameters:

Name	Type	Description
`data`	Object	Data object to be serialized before delivery
`format`	String	the
`callback`	module:tastypie/lib/resource~Nodeback

Source:

lib/resource/index.js

sort(list)

Applies custome sorting to a given list of objects. Default applies no sorting

Parameters:

Name	Type	Description
`list`	Array	The list of objects to be sorted

Source:

lib/resource/index.js

Returns:

Array of sorted objects

throttle(bundle)

manages request throttling. Default implementation usses the remote address of the incomming request

Parameters:

Name	Type	Description
`bundle`	module:tastypie/lib/resource~Bundle	A bundle representing the current request

Source:

lib/resource/index.js

Returns:

true if the request should rejected

Type: Boolean

to_uri(obj, bundle, result)

creates a resource uri for a specific object

Parameters:

Name	Type	Description
`obj`	Object
`bundle`	Bundle
`result`	Object

Source:

lib/resource/index.js

Returns:

Type: String

toString()

returns the internal string representation of a resource

Source:

lib/resource/index.js

Returns:

String representation

Type: String

update_object(bundle, callback)

Method that is responsibe for updating a specific object during a PUT request

Parameters:

Name	Type	Description
`bundle`	module:tastypie/lib/resource~Bundle	The data bundle representing the current request
`callback`	module:tastypie/lib/resource~Nodeback	callback to be called when the operation finishes.

Source:

lib/resource/detail.js

Type Definitions

Bundle

An easy way to pass around request, and reply objects

Type:

Object

Properties:

Name	Type	Argument	Description
`req`	Object		A Hapijs request object
`res`	function		A hapi reply function
`data`	Object		A data object representing an entity for serialization / deserialization
`object`	Object	<optional>	A fully populated data entity. Mostly used internally

Source:

lib/resource/index.js

Nodeback

An easy way to pass around request, and reply objects

Type:

Object

Properties:

Name	Type	Argument	Description
`err`	Error	<optional>
`data`	Object \| Array.<Object>	<optional>	Data returned from an asyn operation

Source:

lib/resource/index.js

RequestError

An easy way to pass around request, and reply objects

Type:

Error

Properties:

Name	Type	Description
`req`	Request
`res`	Reply

Source:

lib/resource/index.js