Resource.md

The Resource class

The Resource class represents a single REST resource in your API. If you are unfamiliar with RESTful API design, here is a good article on the topic.

Every Resource object corresponds to a single URL. That URL consists of two parts:

• Collection
  This is what groups multiple resources of the same type together. For example, the "/users" collection holds user resources, and the "/store/products" collection holds product resources.

• Name
  This is what uniquely identifies a given resource within its collection. For example, "/users/jdoe" is a resource named "/jdoe" in the "/users" collection, and "/store/products/widget.html" is a resource named "/widget.html" in the "/store/products" collection.

Here are some examples of URLs and their corresponding collections and names:

URL	Collection Path	Resource Name
/static/pages/index.html	/static/pages	/index.html
/restaurants/washington/seattle/	/restaurants/washington	/seattle/
/restaurants/washington/seattle/joes-diner	/restaurants/washington/seattle	/joes-diner
/ (the root of your API)	(empty string)	/

TIP: Swagger Express Middleware honors your Express App's settings, such as case-sensitivity and strict-routing. By default, the URLs "/users/jdoe", "/users/JDoe", and "/users/jdoe/" all map to the same Resource object. But if you enable strict routing and case-sensitive routing in your app, then those URLs will be treated as three different resources.

Constructors

Resource(path, data)

• path (required) - string
  The full resource path (such as "/pets/Fido"). The constructor will automatically split the path and set the collection and name properties accordingly.

• data (optional) - any
  The resource's data. This can be any value that is serializable as JSON, such as a string, a number, an object, an array, etc.

Resource(collection, name, data)

• collection (required) - string
  The resource's collection path (such as "/pets").

• name (required) - string
  The resource's unique name within its collection (such as "/Fido").

• data (required) - any
  The resource's data. This can be any value that is serializable as JSON, such as a string, a number, an object, an array, etc.

TIP: Remember, JSON does not support literal values for some JavaScript types. Date objects are serialized as strings (in ISO 8601 format), undefined is sometimes serialized as null (such as when in an array), and RegExp objects are serialized as empty objects. So you might need to sanitize your data prior to passing it to the Resource constructor.

Properties

Property Name	Data Type	Description
collection	string	The resource's collection path. This property can be an empty string, if the resource is at the root of your API. The collection path should always begin with a forward slash and should not end with one. The Resource constructor automatically handles this normalization. For example, "pets/" becomes "/pets".
name	string	The resource's unique name within its collection. This property cannot be an empty string. It will always contain at least a single forward slash. Resource names should always begin with a forward slash and may also end with one. The Resource constructor automatically handles this normalization. For example, "Fido" becomes "/Fido".
data	any	The resource's data. This can be any value that is serializable as JSON.
createdOn	Date object	The date/time that the resource was first saved to a DataStore. This property is automatically set by the DataStore class.
modifiedOn	Date object	The date/time that the resource was last saved (or updated) in a DataStore. This property is automatically set by the DataStore class.

Instance Methods

toString()

The Resource class overrides the default Object.toString() method to return the full resource path (collection + name).

valueOf()

The Resource class overrides the default Object.valueOf() method to return the full resource path (collection + name). It also supports extra parameters to control case-sensitivity and optionally return only the collection name, but these parameters should be considered a private API and should not be used.

merge(other)

Merges the specified data with this resource's data. If the data cannot be merged, then this resource's data is overwritten with the new data.

• other (required) - any or Resource
  The data to be merged. It can be any value that is serializable as JSON, such as a string, a number, an object, an array, etc. If it is another Resource object, then that resource's data will be merged.

Static Methods

parse(json)

Parses JSON data into Resource objects.

• json (required) - string
  The JSON data to be parsed. This JSON data must be one or more Resource objects that were serialized using JSON.stringify(). If the JSON is invalid, then an error will be thrown. If the JSON is a single object, then a single Resource will be returned; otherwise, an array of Resource objects will be returned.