loopback/docs/api-app.md

App object

The App object represents a Loopback application.

The App object extends Express and supports Express / Connect middleware. See Express documentation for details.

var loopback = require('loopback');
var app = loopback();

app.get('/', function(req, res){
  res.send('hello world');
});

app.listen(3000);

Properties

models

The app.models object has properties for all defined models. In the following example the Product and CustomerReceipt models are accessed using the models object.

NOTE: you must call app.boot() to create the app.models object.

var loopback = require('loopback');
var app = loopback();
app.boot({
  dataSources: {
    db: {connector: 'memory'}
  }
});
app.model('product', {dataSource: 'db'});
app.model('customer-receipt', {dataSource: 'db'});

// available based on the given name
var Product = app.models.Product;

// also available as camelCase
var product = app.models.product;

// multi-word models are avaiable as pascal cased
var CustomerReceipt = app.models.CustomerReceipt;

// also available as camelCase
var customerReceipt = app.models.customerReceipt;

Methods

app.boot([options])

Initialize an application from an options object or a set of JSON and JavaScript files.

What happens during an app boot?

1. DataSources are created from an options.dataSources object or datasources.json in the current directory
2. Models are created from an options.models object or models.json in the current directory
3. Any JavaScript files in the ./models directory are loaded with require().

Options

• cwd - optional - the directory to use when loading JSON and JavaScript files
• models - optional - an object containing Model definitions
• dataSources - optional - an object containing DataSource definitions

NOTE: mixing app.boot() and app.model(name, config) in multiple files may result in models being undefined due to race conditions. To avoid this when using app.boot() make sure all models are passed as part of the models definition.

Model Definitions

The following is an example of an object containing two Model definitions: "location" and "inventory".

{
  "dealership": {
    // a reference, by name, to a dataSource definition
    "dataSource": "my-db",
    // the options passed to Model.extend(name, properties, options)
    "options": {
      "relationships": {
        "cars": {
          "type": "hasMany",
          "model": "Car",
          "foreignKey": "dealerId"  
        }
      },
      "remoteMethods": {
        "nearby": {
          "description": "Find nearby locations around the geo point",
          "accepts": [
            {"arg": "here", "type": "GeoPoint", "required": true, "description": "geo location (lat & lng)"}
          ],
          "returns": {"arg": "locations", "root": true}
        }
      }
    },
    // the properties passed to Model.extend(name, properties, options)
    "properties": {
      "id": {"id": true},
      "name": "String",
      "zip": "Number",
      "address": "String"
    }
  },
  "car": {
    "dataSource": "my-db"
    "properties": {
      "id": {
        "type": "String",
        "required": true,
        "id": true
      },
      "make": {
        "type": "String",
        "required": true
      },
      "model": {
        "type": "String",
        "required": true
      }
    }
  }
}

Model definition properties

• dataSource - required - a string containing the name of the data source definition to attach the Model to
• options - optional - an object containing Model options
• properties optional - an object defining the Model properties in LoopBack Definition Language

DataSource definition properties

• connector - required - the name of the connector

model(name, definition)

Define a Model and export it for use by remote clients.

definition

• public - default: true attach the Model to the app and export its methods to clients
• dataSource - required the name of the DataSource to attach the Model to

Example:

// declare a DataSource
app.boot({
  dataSources: {
    db: {
      connector: 'mongodb',
      url: 'mongodb://localhost:27015/my-database-name'
    }
  }
});

// describe a model
var modelDefinition = {dataSource: 'db'};

// create the model
var Product = app.model('product', modelDefinition);

// use the model api
Product.create({name: 'pencil', price: 0.99}, console.log);

Note - This will expose all shared methods on the model.

You may also export an existing Model by calling app.model(Model) like the example below.

models()

Get the app's exported models. Only models defined using app.model() will show up in this list.

var models = app.models();

models.forEach(function (Model) {
  console.log(Model.modelName); // color
});

docs(options)

Enable swagger REST API documentation.

Options

• basePath The basepath for your API - eg. 'http://localhost:3000'.

Example

// enable docs
app.docs({basePath: 'http://localhost:3000'});

Run your app then navigate to the API explorer. Enter your API basepath to view your generated docs.

app.use( router )

Expose models over specified router. For example, to expose models over REST using the loopback.rest router:

app.use(loopback.rest());

View generated REST documentation at http://localhost:3000/_docs.

Middleware

LoopBack includes middleware similar to Express / Connect middleware.

loopback.token(options)

Options

• cookies - An Array of cookie names
• headers - An Array of header names
• params - An Array of param names

Each array is used to add additional keys to find an accessToken for a request.

The following example illustrates how to check for an accessToken in a custom cookie, query string parameter and header called foo-auth.

app.use(loopback.token({
  cookies: ['foo-auth'],
  headers: ['foo-auth', 'X-Foo-Auth'],
  cookies: ['foo-auth', 'foo_auth']
}));

Defaults

By default the following names will be checked. These names are appended to any optional names. They will always be checked, but any names specified will be checked first.

  params.push('access_token');
  headers.push('X-Access-Token');
  headers.push('authorization');
  cookies.push('access_token');
  cookies.push('authorization');

NOTE: The loopback.token() middleware will only check for signed cookies.