collection.md

Table of Contents

• Documentation Home
• lib
  • $express
  • authentication-facebook
  • authentication-google
  • authentication
  • cache
  • collection
  • controller
  • err
  • get
  • interaction
  • mongo
  • refs
  • registerModules
  • registerServices
  • registerThings
  • responses
  • route
  • services
  • set
  • stack
  • start
  • static
  • thing
  • things
  • types

amna.collection

Represents a complete API for a thing. Fully customizable and extendable.

API

Use as an amna Module

// File: amna_modules/colors/module.js

var amna = require('amna');

/**
 * Rest API: Colors
 */
var ColorsAPI = module.exports = amna.collection(amna.things.Color,
                                                 { ... options (optional) ...});

Once registered with amna.registerModules(['colors']);, this sets up the basic CRUD operations for the Color thing.

Default API Routes

The following are the automatically available API routes if no overrides are specified:

GET /colors/schema
    Returns a JSON representation of the thing schema
    Lives at ColorsAPI.routes.collectionGetSchema

GET /colors/autocomplete?{"$input":"bl"}
    Returns colors with a word starting with "bl" (i.e. "light blue", "blue")
    Lives at ColorsAPI.routes.collectionGetAutocomplete

GET /colors ................................. returns first page of non-deleted colors,
                                                at 20 items per page
GET /colors?{"name":"red"} .................. returns first page of non-deleted colors,
                                                at 20 items per page, with name "red"
GET /colors?[{},{"limit":10}] ............... returns first page of non-deleted colors,
                                                at 10 items per page
GET /colors?[{},{"deleted":null}] ........... returns first page of all colors,
                                                at 20 items per page,
                                                whether deleted or not
GET /colors?[{},{"deleted":true}] ........... returns first page of deleted colors,
                                                at 20 items per page
    Lives at ColorsAPI.routes.collectionGet

POST /colors
    Creates a color (or multiple colors if body is [{...}, {...}, ...])
    Lives at ColorsAPI.routes.collectionPost

GET /colors/:id
    Returns a single color by id
    Lives at ColorsAPI.routes.documentGet

PUT /colors/:id
    Updates a single color by id
    Lives at ColorsAPI.routes.documentPut

DELETE /colors/:id
    Deletes a single color by id
    Lives at ColorsAPI.routes.documentDelete

Any of the default routes can be disabled by specifying the name of the route in the options object, with a value of false.

Example:

/**
 * Rest API: Colors
 */
var ColorsAPI = module.exports = amna.collection(amna.things.Color,
                                                 {documentDelete: false,
                                                  collectionGetSchema: false,
                                                  collectionGetAutocomplete: false});

Now, the routes for deleting a color, getting the color schema, or autocompleting a color name will all cause a 404 not found error, unless you add custom routes to replace them.

To further understand how you can work with these and other routes, please see the documentation section on amna.route. All ColorsAPI.routes.* are instances of amna.route.

Custom API Routes

Extending the default set of collection routes is super easy. Choose one of the following methods based on the scope (collection or document) and method you intend to use for the route.

All extension helpers:

ColorsAPI.collectionGet(url, function (self) { ... });
ColorsAPI.collectionPost(url, function (self) { ... });
ColorsAPI.collectionPut(url, function (self) { ... });
ColorsAPI.collectionDelete(url, function (self) { ... });

ColorsAPI.documentGet(url, function (self) { ... });
ColorsAPI.documentPost(url, function (self) { ... });
ColorsAPI.documentPut(url, function (self) { ... });
ColorsAPI.documentDelete(url, function (self) { ... });

The variable self is an instance of amna.interaction.

Example:

ColorsAPI.collectionGet('/info', function (self) {
    self.done('This is the Colors API');
});

Then, if you were to visit /colors/info in your browser, you would get the following API response:

{
    "status": "ok",
    "data": "This is the Colors API"
}