CollectionsΒΆ

Carbond Collections provide a high-level abstraction for defining Endpoints that behave like a collection of resources. When you define a Collection you may define handlers for the following operations:

  • insert(objects, options, context)
  • find(options, context)
  • save(objects, options, context)
  • update(update, options, context)
  • remove(options, context)
  • insertObject(object, options, context)
  • findObject(id, options, context)
  • saveObject(object, options, context)
  • updateObject(id, update, options, context)
  • removeObject(id, options, context)

Which results in the following tree of Endpoints and Operations:

For example, here is a Collection that enables the find operation and defines a handler:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
var carbon = require('carbon-io')

var __ = carbon.fibers.__(module)
var _o = carbon.bond._o(module)
var o = carbon.atom.o(module)

__(function() {
  module.exports = o.main({
    _type: carbon.carbond.Service,
    port: 8888,
    dbUri: "mongodb://localhost:27017/mydb",
    endpoints: {
      feedback: o({
        _type: carbon.carbond.collections.Collection,
        enabled: {
          find: true
        },
        find: function(options) {
          /*
           * implementation...
           */
        }
      })
    }
  })
})

The Collection class handles much of the HTTP boilerplate code you would typically have to implement to build an API. See Collection Operation (REST) Interface for more information.

Collection Endpoints and operations

Collection Endpoints can be created either by creating an instance of a Collection (most common) or by sub-classing (e.g. the MongoDBCollection class). You can configure Collections (see Collection Configuration) via top-level properties.

Collection Endpoints can support multiple operations (e.g., insert, insertObject, find, findObject, etc.). In most cases, you should only need to define the appropriate operation handlers and enable them (see Enabling / Disabling Operations).

If your use case requires further configuration of the Collection operation handler (e.g. modify behavior at the HTTP level), you can use the appropriate Collection operation config properties to do so. See Collection Operation Configuration for more information.

Enabling / Disabling Operations

Collection operation handlers can be enabled and disabled using the enabled property. All operations are disabled by default. To enable an operation you have to explicitly mark it as enabled:

...
enabled: {find: true},
...

If you want to enable all operations, you can use the * property:

...
enabled: {'*': true},
...

If you want to enable all operations but the find operation:

...
enabled: {find: false, '*': true},
...

When instantiating a concrete Collection implementation, you will likely have to do little else than name the Collection and enable the operations that you want exposed to the user:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
var path = require('path')

var carbon = require('carbon-io')

var __ = carbon.fibers.__(module)
var _o = carbon.bond._o(module)
var o = carbon.atom.o(module)

__(function() {
  module.exports = o.main({
    _type: carbon.carbond.Service,
    port: 8888,
    dbUri: "mongodb://localhost:27017/mydb",
    endpoints: {
      feedback: o({
        _type: carbon.carbond.mongodb.MongoDBCollection,
        enabled: {
          find: true
        }
      })
    }
  })
})

Collection Configuration

Collections support configuration at multiple levels with two types of configuration: Collection-level configuration, which may have implications for certain Collection operations, and CollectionOperation-specific configs.

The base Collection configuration consists of a few properties:

  • enabled - see `Enabling / Disabling Operations`_
  • schema - this is the schema for all objects in the Collection. It must be of type object and contain an ID property whose name is the same as the value of idParameterName.
  • example - this is an example object in the Collection and is used for documentation.
  • idGenerator - if present, this must be an object with at least one method: generateId. This method will be passed the Collection instance along with the current Request object and should return a suitable ID for the object being inserted on insert or insertObject.
  • idPathParameterName- this is the name of the path parameter used to capture an object ID for object specific endpoints (e.g. /<someCollectionName>/:<idPathParameterName>).
  • idParameterName - this is the name of the ID property of a Collection object (e.g. {<idParameterName>: "foo", "bar": "baz"}).
  • idHeaderName - this is the name of the HTTP response header that will contain the EJSON serialized object ID or IDs when objects are created in the Collection.

Note: most of these properties already have sane defaults (see the Collection class reference for more details).

You can also configure CollectionOperation-specific configs. See Collection Operation Configuration for more information.