View on GitHub

hapi-mongoose-resource

resourceful mongoose objects for the hapi framework

Download this project as a .zip file Download this project as a tar.gz file

hapi-mongoose-resource api

resource

a resource is an object that is used to generate routes and maintain handlers for a schema.

properties

model

a model instance of a mongoose.Schema object passed to the constructor; the base of the resource.

path

a string passed to the constructor that forms the base of the routes.

router

an object that builds the routes mapping paths and verbs to handler methods.

handler

an object that controls the database interactions for the given schema.

options

an object passed to the constructor that defines optional configuration parameters.

defaults

resource_key

_id property of the schema. it's used to contract paths.

optional configurations

refs

used by the handler

an object mapping schema properties to other resources.

for example, if you had the following schemas/models/resources:

mongoose = require 'mongoose'
Resource = require 'hapi-mongoose-resource'

ComponentSchema = new mongoose.Schema { name: String }
Component = mongoose.model 'Component', ComponentSchema
ComponentResource = new Resource Component, '/components'

ProductSchema = new mongoose.Schema { name: String, components: [{ type: mongoose.Schema.Types.ObjectId, ref: Component }]
Product = mongoose.model 'Product', ProductSchema
ProductResource = new Resource Product, '/products', { refs: { components: ComponentResource } }

and made a GET requests to whatever.com/products, your response objects would look like:

{
  "name": "Some Finished Product",
  "components": [
    "/components/<ObjectId>",
    "/components/<ObjectId>",
    "/components/<ObjectId>",
    "/components/<ObjectId>"
  ]
}

where <ObjectId> is replaced by the actual object ids of the components that were named when you created the product. this may not seem like much, but it could save a lot of work on front-end applications and minimize the chance of pushing broken links to related/referenced objects.

router

a router is an internal object of a resource. it is used to build routing paths for a hapi server instance.

properties

routes

an array of objects that meet the specs for hapi server routing.

handler

an instance of a resource.handler object passed to the constructor. it's methods are mapped to the paths.

path

a string passed to the constructor. it is the base path used for routing.

options

an object passed to the constructor that defines optional configuration parameters.

defaults

routes

routes by default map to the standard CRUD verbs: GET, CREATE, UPDATE, and DELETE. GET is special in the sense that it can fetch either a single resource or a collection of resources.

the other verbs must be called with an identifying parameter in their uri -- most typically the _id field of the model/document.

handler

a handler performs all the database interactions for a schema/model.

properties

model

the same model passed to the parent resource.

path

the same path passed to the parent resource.

options

an object passed to the constructor that defines optional configuration parameters.

defaults

resource_uri

this is not configurable - you cannot turn this off

for every document returned, an additional property will be added to it with the key resource_uri.

for many cases, you will be directly calling the object by it's id; however, when looking up items, it's helpful for the document to contain a self-referring uri that can be easily parsed and used for absolute linking.

for example, if you have a Widget resource, and you called to /widgets?weight:{"$lt":3} via GET, you would receive something like this:

[
  {
    "name": "Widget Alpha",
    "weight": 2.3,
    "_id": "whatever-widget-alpha",
    "resource_uri": "/widgets/whatever-widget-alpha"
  },
  {
    "name": "Widget Beta",
    "weight": 1.9,
    "_id": "whatever-widget-beta",
    "resource_uri": "/widgets/whatever-widget-beta"
  },
  {
    "name": "Widget Gamma",
    "weight": 2.8,
    "_id": "whatever-widget-gamma",
    "resource_uri": "/widgets/whatever-widget-gamma"
  }
]

thus making it easier for a front-end application to link directly to the resources.