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:

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

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.