verdnatura-mirror
/
loopback
mirror of https://github.com/strongloop/loopback.git
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #132 from strongloop/feature/move-app-doc-to-jsdox 

Move the documentation of app object to jsdox
This commit is contained in:
Miroslav Bajtoš 2014-01-14 23:59:06 -08:00
parent 191d52995e eabe29bb73
commit f155ba46c7
9 changed files with 134 additions and 819 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs.json
View File

@ -15,8 +15,7 @@
"docs/api-datasource.md", "docs/api-datasource.md",
"docs/api-geopoint.md", "docs/api-geopoint.md",
"docs/api-model.md", "docs/api-model.md",
"docs/api-model-remote.md", "docs/api-model-remote.md"
"docs/rest.md"
], ],
"assets": "/docs/assets" "assets": "/docs/assets"
} }

255
docs/api-app.md
View File

@ -1,255 +0,0 @@
## App object
The App object represents a Loopback application.
The App object extends [Express](http://expressjs.com/api.html#express) and supports [Express / Connect middleware](http://expressjs.com/api.html#middleware). See [Express documentation](http://expressjs.com/api.html) for details.
```js
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.
```js
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()`.
4. Any JavaScript files in the `./boot` 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.
<a name="model-definition"></a>
**Model Definitions**
The following is an example of an object containing two `Model` definitions: "location" and "inventory".
```js
{
"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](http://docs.strongloop.com/loopback-datasource-juggler/#loopback-definition-language)
**DataSource definition properties**
- `connector` - **required** - the name of the [connector](#working-with-data-sources-and-connectors)
### 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:
```js
// 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](#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.
```js
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**
```js
// enable docs
app.docs({basePath: 'http://localhost:3000'});
```
Run your app then navigate to [the API explorer](http://petstore.swagger.wordnik.com/). 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:
```js
app.use(loopback.rest());
```
View generated REST documentation at [http://localhost:3000/_docs](http://localhost:3000/_docs).
### Middleware
LoopBack includes middleware similar to [Express / Connect middleware](http://expressjs.com/api.html#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`.
```js
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.
```js
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](http://expressjs.com/api.html#req.signedCookies).

14
docs/api-datasource.md
View File

@ -14,9 +14,9 @@ var oracle = loopback.createDataSource({
}); });
``` ```
## Methods ### Methods
### dataSource.createModel(name, properties, options) #### dataSource.createModel(name, properties, options)
Define a model and attach it to a `DataSource`. Define a model and attach it to a `DataSource`.
@ -42,7 +42,7 @@ var Customer = ds.createModel('Customer', {
}); });
``` ```
### dataSource.discoverModelDefinitions([username], fn) #### dataSource.discoverModelDefinitions([username], fn)
Discover a set of model definitions (table or collection names) based on tables or collections in a data source. Discover a set of model definitions (table or collection names) based on tables or collections in a data source.
@ -57,7 +57,7 @@ oracle.discoverModelDefinitions(function (err, models) {
}); });
``` ```
### dataSource.discoverSchema([owner], name, fn) #### dataSource.discoverSchema([owner], name, fn)
Discover the schema of a specific table or collection. Discover the schema of a specific table or collection.
@ -156,12 +156,12 @@ Discover the schema of a specific table or collection.
} }
``` ```
### dataSource.enableRemote(operation) #### dataSource.enableRemote(operation)
Enable remote access to a data source operation. Each [connector](#connector) has its own set of set remotely enabled and disabled operations. You can always list these by calling `dataSource.operations()`. Enable remote access to a data source operation. Each [connector](#connector) has its own set of set remotely enabled and disabled operations. You can always list these by calling `dataSource.operations()`.
### dataSource.disableRemote(operation) #### dataSource.disableRemote(operation)
Disable remote access to a data source operation. Each [connector](#connector) has its own set of set enabled and disabled operations. You can always list these by calling `dataSource.operations()`. Disable remote access to a data source operation. Each [connector](#connector) has its own set of set enabled and disabled operations. You can always list these by calling `dataSource.operations()`.
@ -184,7 +184,7 @@ oracle.disableRemote('destroyAll');
- disabling the remoting for a method only affects client access (it will still be available from server models) - disabling the remoting for a method only affects client access (it will still be available from server models)
- data sources must enable / disable operations before attaching or creating models - data sources must enable / disable operations before attaching or creating models
### dataSource.operations() #### dataSource.operations()
List the enabled and disabled operations. List the enabled and disabled operations.

12
docs/api-geopoint.md
View File

@ -40,9 +40,9 @@ CoffeeShop.find({where: {location: {near: here}}, limit:3}, function(err, nearby
- `feet` - `feet`
- `degrees` - `degrees`
## Methods ### Methods
### geoPoint.distanceTo(geoPoint, options) #### geoPoint.distanceTo(geoPoint, options)
Get the distance to another `GeoPoint`. Get the distance to another `GeoPoint`.
@ -52,7 +52,7 @@ var there = new GeoPoint({lat: 5, lng: 5});
console.log(here.distanceTo(there, {type: 'miles'})); // 438 console.log(here.distanceTo(there, {type: 'miles'})); // 438
``` ```
### GeoPoint.distanceBetween(a, b, options) #### GeoPoint.distanceBetween(a, b, options)
Get the distance between two points. Get the distance between two points.
@ -60,12 +60,12 @@ Get the distance between two points.
GeoPoint.distanceBetween(here, there, {type: 'miles'}) // 438 GeoPoint.distanceBetween(here, there, {type: 'miles'}) // 438
``` ```
## Properties ### Properties
### geoPoint.lat #### geoPoint.lat
The latitude point in degrees. Range: -90 to 90. The latitude point in degrees. Range: -90 to 90.
### geoPoint.lng #### geoPoint.lng
The longitude point in degrees. Range: -180 to 180. The longitude point in degrees. Range: -180 to 180.

10
docs/api-model-remote.md
View File

@ -2,7 +2,9 @@
You can expose a Model's instance and static methods to clients. A remote method must accept a callback with the conventional `fn(err, result, ...)` signature. You can expose a Model's instance and static methods to clients. A remote method must accept a callback with the conventional `fn(err, result, ...)` signature.
### loopback.remoteMethod(fn, [options]) ### Static Methods
#### loopback.remoteMethod(fn, [options])
Expose a remote method. Expose a remote method.
@ -118,7 +120,7 @@ as follows (assuming `name` as the name of the input parameter to resolve):
then the value of `args['name']` is used if it is defined. then the value of `args['name']` is used if it is defined.
2. Otherwise `req.param('name')` is returned. 2. Otherwise `req.param('name')` is returned.
## Remote hooks ### Remote hooks
Run a function before or after a remote method is called by a client. Run a function before or after a remote method is called by a client.
@ -185,9 +187,9 @@ A `Model` representing the user calling the method remotely. **Note:** this is u
During `afterRemote` hooks, `ctx.result` will contain the data about to be sent to a client. Modify this object to transform data before it is sent. During `afterRemote` hooks, `ctx.result` will contain the data about to be sent to a client. Modify this object to transform data before it is sent.
#### Rest #### REST
When [loopback.rest](#loopbackrest) is used the following `ctx` properties are available. When [loopback.rest](#loopbackrest) is used the following additional `ctx` properties are available.
##### ctx.req ##### ctx.req

68
docs/api-model.md
View File

@ -31,9 +31,9 @@ var User = loopback.createModel('user', {
}); });
``` ```
## Methods ### Methods
### Model.attachTo(dataSource) #### Model.attachTo(dataSource)
Attach a model to a [DataSource](#data-source). Attaching a [DataSource](#data-source) updates the model with additional methods and behaviors. Attach a model to a [DataSource](#data-source). Attaching a [DataSource](#data-source) updates the model with additional methods and behaviors.
@ -51,9 +51,9 @@ User.attachTo(oracle);
**Note:** until a model is attached to a data source it will **not** have any **attached methods**. **Note:** until a model is attached to a data source it will **not** have any **attached methods**.
## Properties ### Properties
### Model.properties #### Model.properties
An object containing a normalized set of properties supplied to `loopback.createModel(name, properties)`. An object containing a normalized set of properties supplied to `loopback.createModel(name, properties)`.
@ -92,7 +92,7 @@ Outputs:
} }
``` ```
## CRUD and Query Mixins ### CRUD and Query Mixins
Mixins are added by attaching a vanilla model to a [data source](#data-source) with a [connector](#connectors). Each [connector](#connectors) enables its own set of operations that are mixed into a `Model` as methods. To see available methods for a data source call `dataSource.operations()`. Mixins are added by attaching a vanilla model to a [data source](#data-source) with a [connector](#connectors). Each [connector](#connectors) enables its own set of operations that are mixed into a `Model` as methods. To see available methods for a data source call `dataSource.operations()`.
@ -146,11 +146,11 @@ Here is the definition of the `count()` operation.
} }
``` ```
## Static Methods ### Static Methods
**Note:** These are the default mixin methods for a `Model` attached to a data source. See the specific connector for additional API documentation. **Note:** These are the default mixin methods for a `Model` attached to a data source. See the specific connector for additional API documentation.
### Model.create(data, [callback]) #### Model.create(data, [callback])
Create an instance of Model with given data and save to the attached data source. Callback is optional. Create an instance of Model with given data and save to the attached data source. Callback is optional.
@ -162,7 +162,7 @@ User.create({first: 'Joe', last: 'Bob'}, function(err, user) {
**Note:** You must include a callback and use the created model provided in the callback if your code depends on your model being saved or having an `id`. **Note:** You must include a callback and use the created model provided in the callback if your code depends on your model being saved or having an `id`.
### Model.count([query], callback) #### Model.count([query], callback)
Query count of Model instances in data source. Optional query param allows to count filtered set of Model instances. Query count of Model instances in data source. Optional query param allows to count filtered set of Model instances.
@ -172,7 +172,7 @@ User.count({approved: true}, function(err, count) {
}); });
``` ```
### Model.find(filter, callback) #### Model.find(filter, callback)
Find all instances of Model, matched by query. Fields used for filter and sort should be declared with `{index: true}` in model definition. Find all instances of Model, matched by query. Fields used for filter and sort should be declared with `{index: true}` in model definition.
@ -230,7 +230,7 @@ User.find({
**Note:** See the specific connector's [docs](#connectors) for more info. **Note:** See the specific connector's [docs](#connectors) for more info.
### Model.destroyAll([where], callback) #### Model.destroyAll([where], callback)
Delete all Model instances from data source. **Note:** destroyAll method does not perform destroy hooks. Delete all Model instances from data source. **Note:** destroyAll method does not perform destroy hooks.
@ -242,7 +242,7 @@ Product.destroyAll({price: {gt: 99}}, function(err) {
> **NOTE:* `where` is optional and a where object... do NOT pass a filter object > **NOTE:* `where` is optional and a where object... do NOT pass a filter object
### Model.findById(id, callback) #### Model.findById(id, callback)
Find instance by id. Find instance by id.
@ -252,7 +252,7 @@ User.findById(23, function(err, user) {
}); });
``` ```
### Model.findOne(where, callback) #### Model.findOne(where, callback)
Find a single instance that matches the given where expression. Find a single instance that matches the given where expression.
@ -262,11 +262,11 @@ User.findOne({id: 23}, function(err, user) {
}); });
``` ```
### Model.upsert(data, callback) #### Model.upsert(data, callback)
Update when record with id=data.id found, insert otherwise. **Note:** no setters, validations or hooks applied when using upsert. Update when record with id=data.id found, insert otherwise. **Note:** no setters, validations or hooks applied when using upsert.
### Custom static methods #### Custom static methods
Define a static model method. Define a static model method.
@ -307,11 +307,11 @@ loopback.remoteMethod(
); );
``` ```
## Instance methods ### Instance methods
**Note:** These are the default mixin methods for a `Model` attached to a data source. See the specific connector for additional API documentation. **Note:** These are the default mixin methods for a `Model` attached to a data source. See the specific connector for additional API documentation.
### model.save([options], [callback]) #### model.save([options], [callback])
Save an instance of a Model to the attached data source. Save an instance of a Model to the attached data source.
@ -326,7 +326,7 @@ joe.save(function(err, user) {
}); });
``` ```
### model.updateAttributes(data, [callback]) #### model.updateAttributes(data, [callback])
Save specified attributes to the attached data source. Save specified attributes to the attached data source.
@ -337,7 +337,7 @@ user.updateAttributes({
}, fn); }, fn);
``` ```
### model.destroy([callback]) #### model.destroy([callback])
Remove a model from the attached data source. Remove a model from the attached data source.
@ -347,7 +347,7 @@ model.destroy(function(err) {
}); });
``` ```
### Custom instance methods #### Custom instance methods
Define an instance method. Define an instance method.
@ -363,9 +363,9 @@ Define a remote model instance method.
loopback.remoteMethod(User.prototype.logout) loopback.remoteMethod(User.prototype.logout)
``` ```
## Relationships ### Relationships
### Model.hasMany(Model, options) #### Model.hasMany(Model, options)
Define a "one to many" relationship. Define a "one to many" relationship.
@ -407,7 +407,7 @@ Book.create(function(err, book) {
}); });
``` ```
### Model.belongsTo(Model, options) #### Model.belongsTo(Model, options)
A `belongsTo` relation sets up a one-to-one connection with another model, such A `belongsTo` relation sets up a one-to-one connection with another model, such
that each instance of the declaring model "belongs to" one instance of the other that each instance of the declaring model "belongs to" one instance of the other
@ -428,7 +428,7 @@ in one of the following styles:
post.author(user) // Set the author to be the given user post.author(user) // Set the author to be the given user
``` ```
### Model.hasAndBelongsToMany(Model, options) #### Model.hasAndBelongsToMany(Model, options)
A `hasAndBelongsToMany` relation creates a direct many-to-many connection with A `hasAndBelongsToMany` relation creates a direct many-to-many connection with
another model, with no intervening model. For example, if your application another model, with no intervening model. For example, if your application
@ -443,9 +443,9 @@ appearing in many groups, you could declare the models this way,
user.groups.remove(group, callback); // remove the user from the group user.groups.remove(group, callback); // remove the user from the group
``` ```
## Validations ### Validations
### Model.validatesFormatOf(property, options) #### Model.validatesFormatOf(property, options)
Require a model to include a property that matches the given format. Require a model to include a property that matches the given format.
@ -453,7 +453,7 @@ Require a model to include a property that matches the given format.
User.validatesFormat('name', {with: /\w+/}); User.validatesFormat('name', {with: /\w+/});
``` ```
### Model.validatesPresenceOf(properties...) #### Model.validatesPresenceOf(properties...)
Require a model to include a property to be considered valid. Require a model to include a property to be considered valid.
@ -461,7 +461,7 @@ Require a model to include a property to be considered valid.
User.validatesPresenceOf('first', 'last', 'age'); User.validatesPresenceOf('first', 'last', 'age');
``` ```
### Model.validatesLengthOf(property, options) #### Model.validatesLengthOf(property, options)
Require a property length to be within a specified range. Require a property length to be within a specified range.
@ -469,7 +469,7 @@ Require a property length to be within a specified range.
User.validatesLengthOf('password', {min: 5, message: {min: 'Password is too short'}}); User.validatesLengthOf('password', {min: 5, message: {min: 'Password is too short'}});
``` ```
### Model.validatesInclusionOf(property, options) #### Model.validatesInclusionOf(property, options)
Require a value for `property` to be in the specified array. Require a value for `property` to be in the specified array.
@ -477,7 +477,7 @@ Require a value for `property` to be in the specified array.
User.validatesInclusionOf('gender', {in: ['male', 'female']}); User.validatesInclusionOf('gender', {in: ['male', 'female']});
``` ```
### Model.validatesExclusionOf(property, options) #### Model.validatesExclusionOf(property, options)
Require a value for `property` to not exist in the specified array. Require a value for `property` to not exist in the specified array.
@ -485,7 +485,7 @@ Require a value for `property` to not exist in the specified array.
User.validatesExclusionOf('domain', {in: ['www', 'billing', 'admin']}); User.validatesExclusionOf('domain', {in: ['www', 'billing', 'admin']});
``` ```
### Model.validatesNumericalityOf(property, options) #### Model.validatesNumericalityOf(property, options)
Require a value for `property` to be a specific type of `Number`. Require a value for `property` to be a specific type of `Number`.
@ -493,7 +493,7 @@ Require a value for `property` to be a specific type of `Number`.
User.validatesNumericalityOf('age', {int: true}); User.validatesNumericalityOf('age', {int: true});
``` ```
### Model.validatesUniquenessOf(property, options) #### Model.validatesUniquenessOf(property, options)
Ensure the value for `property` is unique in the collection of models. Ensure the value for `property` is unique in the collection of models.
@ -509,7 +509,7 @@ Currently supported in these connectors:
- [Oracle](http://github.com/strongloop/loopback-connector-oracle) - [Oracle](http://github.com/strongloop/loopback-connector-oracle)
- [MongoDB](http://github.com/strongloop/loopback-connector-mongodb) - [MongoDB](http://github.com/strongloop/loopback-connector-mongodb)
### myModel.isValid() #### myModel.isValid()
Validate the model instance. Validate the model instance.
@ -526,7 +526,7 @@ user.isValid(function (valid) {
}); });
``` ```
### loopback.ValidationError #### loopback.ValidationError
`ValidationError` is raised when the application attempts to save an invalid `ValidationError` is raised when the application attempts to save an invalid
model instance. model instance.
@ -582,6 +582,6 @@ MyModel.prototype.preflight = function(changes, callback) {
} }
``` ```
## Shared methods ### Shared methods
Any static or instance method can be decorated as `shared`. These methods are exposed over the provided transport (eg. [loopback.rest](#rest)). Any static or instance method can be decorated as `shared`. These methods are exposed over the provided transport (eg. [loopback.rest](#rest)).

8
docs/api.md
View File

@ -1,8 +0,0 @@
## Node.js API
* [App](#app-object)
* [DataSource](#data-source-object)
* [GeoPoint](#geopoint-object)
* [Model](#model-object)
* [Remote methods and hooks](#remote-methods-and-hooks)
* [REST API](#rest-api)

495
docs/rest.md
View File

@ -1,495 +0,0 @@
##create
Create a new instance of the model and persist it into the data source
**Definition**
POST /locations
**Arguments**
* **data** The model instance data
**Example**
Request:
curl -X POST -H "Content-Type:application/json" \
-d '{"name": "L1", "street": "107 S B St", "city": "San Mateo", "zipcode": "94401"}' \
http://localhost:3000/locations
Response:
{
"id": "96",
"street": "107 S B St",
"city": "San Mateo",
"zipcode": 94401,
"name": "L1",
"geo": {
"lat": 37.5670042,
"lng": -122.3240212
}
}
**Errors**
None
##upsert
Update an existing model instance or insert a new one into the data source
**Definition**
PUT /locations
**Arguments**
* **data** The model instance data
**Examples**
Request - insert:
curl -X PUT -H "Content-Type:application/json" \
-d '{"name": "L1", "street": "107 S B St", "city": "San Mateo", "zipcode": "94401"}' \
http://localhost:3000/locations
Response:
{
"id": "98",
"street": "107 S B St",
"city": "San Mateo",
"zipcode": 94401,
"name": "L1",
"geo": {
"lat": 37.5670042,
"lng": -122.3240212
}
}
Request - update:
curl -X PUT -H "Content-Type:applicatin/json" \
-d '{"id": "98", "name": "L4", "street": "107 S B St", "city": "San Mateo", \
"zipcode": "94401"}' http://localhost:3000/locations
Response:
{
"id": "98",
"street": "107 S B St",
"city": "San Mateo",
"zipcode": 94401,
"name": "L4"
}
**Errors**
None
##exists
Check whether a model instance exists by ID in the data source.
**Definition**
GET /locations/exists
**Arguments**
* **id** The model id
**Example**
Request:
curl http://localhost:3000/locations/88/exists
Response:
{
"exists": true
}
**Errors**
None
##findById
Find a model instance by ID from the data source.
**Definition**
GET /locations/{id}
**Arguments**
* **id** The model id
**Example**
Request:
curl http://localhost:3000/locations/88
Response:
{
"id": "88",
"street": "390 Lang Road",
"city": "Burlingame",
"zipcode": 94010,
"name": "Bay Area Firearms",
"geo": {
"lat": 37.5874391,
"lng": -122.3381437
}
}
**Errors**
None
##find
Find all instances of the model matched by filter from the data source.
**Definition**
GET /locations
**Arguments**
Pass the arguments as the value of the `find` HTTP query parameter, as follows
/modelName?filter=[filterType1]=<val1>&filter[filterType2]=<val2>...
where *filterType1*, *filterType2*, and so on, are the filter types, and *val1*, *val2* are the corresponding
values, as described in the following table.
| Filter type | Type | Description |
| ------------- | ------------- | ---------------|
| where | Object | Search criteria. Format: `{key: val}` or `{key: {op: val}}` For list of valid operations, see Operations, below. |
| include | String, Object, or Array | Allows you to load relations of several objects and optimize numbers of requests. For format, see Include format, below. |
| order | String | Sort order. Format: 'key1 ASC, key2 DESC', where ASC specifies ascending and DESC specifies descending order. |
|limit| Number | Maximum number of instances to return. |
|skip (offset) | Number | Skip the specified number of instances. Use offset as alternative. |
|fields| Object, Array, or String | The included/excluded fields. For foramt, see fields below.
**Operations available in where filter**:
* gt: >
* gte: >=
* lt: <
* lte: <=
* between
* inq: IN
* nin: NOT IN
* neq: !=
* like: LIKE
* nlike: NOT LIKE
**Include format**:
* 'posts': Load posts
* ['posts', 'passports']: Load posts and passports
* {'owner': 'posts'}: Load owner and owner's posts
* {'owner': ['posts', 'passports']}: Load owner, owner's posts, and owner's passports
* {'owner': [{posts: 'images'}, 'passports']}: Load owner, owner's posts, owner's posts' images, and owner's passports
**Fields format**:
- `['foo']` or `'foo'` - include only the foo property
- `['foo', 'bar']` - include the foo and bar properties
- `{foo: true}` - include only foo
- `{bat: false}` - include all properties, exclude bat
For example,
- '/weapons': Weapons
- '/weapons?filter[limit]=2&filter[offset]=5': Paginated Weapons
- '/weapons?filter[where][name]=M1911': Weapons with name M1911
- '/weapons?filter[where][audibleRange][lt]=10': Weapons with audioRange < 10
- '/weapons?filter[fields][name]=1&filter[fields][effectiveRange]=1': Only name and effective ranges
- '/weapons?filter[where][effectiveRange][gt]=900&filter[limit]=3': The top 3 weapons with a range over 900 meters
- '/weapons?filter[order]=audibleRange%20DESC&filter[limit]=3': The loudest 3 weapons
- '/locations': Locations
- '/locations?filter[where][geo][near]=153.536,-28.1&filter[limit]=3': The 3 closest locations to a given geo point
**Example**
Request:
Find without filter:
curl http://localhost:3000/locations
Find with a filter:
curl http://localhost:3000/locations?filter%5Blimit%5D=2
**Note**: For curl, `[` needs to be encoded as `%5B`, and `]` as `%5D`.
Response:
[
{
"id": "87",
"street": "7153 East Thomas Road",
"city": "Scottsdale",
"zipcode": 85251,
"name": "Phoenix Equipment Rentals",
"geo": {
"lat": 33.48034450000001,
"lng": -111.9271738
}
},
{
"id": "88",
"street": "390 Lang Road",
"city": "Burlingame",
"zipcode": 94010,
"name": "Bay Area Firearms",
"geo": {
"lat": 37.5874391,
"lng": -122.3381437
}
}
]
**Errors**
None
##findOne
Find first instance of the model matched by filter from the data source.
**Definition**
GET /locations/findOne
**Arguments**
* **filter** The filter that defines where, order, fields, skip, and limit. It's
same as find's filter argument. Please see [find](#find) for more details.
**Example**
Request:
curl http://localhost:3000/locations/findOne?filter%5Bwhere%5D%5Bcity%5D=Scottsdale
Response:
{
"id": "87",
"street": "7153 East Thomas Road",
"city": "Scottsdale",
"zipcode": 85251,
"name": "Phoenix Equipment Rentals",
"geo": {
"lat": 33.48034450000001,
"lng": -111.9271738
}
}
**Errors**
None
##deleteById
Delete a model instance by id from the data source
**Definition**
DELETE /locations/{id}
**Arguments**
* **id** The model id
**Example**
Request:
curl -X DELETE http://localhost:3000/locations/88
Response:
Example TBD.
**Errors**
None
##count
Count instances of the model matched by where from the data source
**Definition**
GET /locations/count
**Arguments**
* **where** The criteria to match model instances
**Example**
Request - count without "where" filter
curl http://localhost:3000/locations/count
Request - count with a "where" filter
curl http://localhost:3000/locations/count?where%5bcity%5d=Burlingame
Response:
{
count: 6
}
**Errors**
None
##nearby
Find nearby locations around the geo point.
**Definition**
GET /locations/nearby
**Arguments**
* **here** geo location object with `lat` and `lng` properties
* **page** number of pages (page size=10)
* **max** max distance in miles
**Example**
Request:
curl http://localhost:3000/locations/nearby?here%5Blat%5D=37.587409&here%5Blng%5D=-122.338225
Response:
[
{
"id": "88",
"street": "390 Lang Road",
"city": "Burlingame",
"zipcode": 94010,
"name": "Bay Area Firearms",
"geo": {
"lat": 37.5874391,
"lng": -122.3381437
}
},
{
"id": "89",
"street": "1850 El Camino Real",
"city": "Menlo Park",
"zipcode": 94027,
"name": "Military Weaponry",
"geo": {
"lat": 37.459525,
"lng": -122.194253
}
}
]
**Errors**
None
##updateAttributes
Update attributes for a model instance and persist it into the data source
**Definition**
PUT /locations/{id}
**Arguments**
* **data** An object containing property name/value pairs
* **id** The model id
**Example**
Request:
curl -X PUT -H "Content-Type:application/json" -d '{"name": "L2"}' \
http://localhost:3000/locations/88
Response:
{
"id": "88",
"street": "390 Lang Road",
"city": "Burlingame",
"zipcode": 94010,
"name": "L2",
"geo": {
"lat": 37.5874391,
"lng": -122.3381437
},
"state": "CA"
}
**Errors**
* 404 No instance found for the given id
##getAssociatedModel
Follow the relations from one model (`location`) to another one (`inventory`) to
get instances of the associated model.
**Definition**
GET /locations/{id}/inventory
**Arguments**
* **id** The id for the location model
**Example**
Request:
curl http://localhost:3000/locations/88/inventory
Response:
[
{
"productId": "2",
"locationId": "88",
"available": 10,
"total": 10
},
{
"productId": "3",
"locationId": "88",
"available": 1,
"total": 1
}
]
**Errors**
None

86
lib/application.js
View File

@ -31,10 +31,10 @@ var DataSource = require('loopback-datasource-juggler').DataSource
* ``` * ```
* *
* @class LoopBackApplication * @class LoopBackApplication
* @header app = loopback() * @header var app = loopback()
*/ */
function App() { function App() {
// no op // this is a dummy placeholder for jsdox
} }
/*! /*!
@ -122,9 +122,55 @@ app.model = function (Model, config) {
} }
/** /**
* Get all exposed models. * Get the models exported by the app. Only models defined using `app.model()`
* will show up in this list.
*
* There are two ways how to access models.
*
* **1. A list of all models**
*
* Call `app.models()` to get a list of all models.
*
* ```js
* var models = app.models();
*
* models.forEach(function (Model) {
* console.log(Model.modelName); // color
* });
* ```
*
* **2. By model name**
*
* `app.model` has properties for all defined models.
*
* In the following example the `Product` and `CustomerReceipt` models are
* accessed using the `models` object.
*
* ```js
* 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;
* ```
* *
* @header app.models() or app.models.ModelName
* @returns {Array} a list of model classes * @returns {Array} a list of model classes
*/ */
@ -172,8 +218,28 @@ app.remotes = function () {
return this._remotes || (this._remotes = RemoteObjects.create()); return this._remotes || (this._remotes = RemoteObjects.create());
} }
/*! /**
* Enable documentation * Enable swagger REST API documentation.
*
* > Note: This method is deprecated, use the extension
* [loopback-explorer](http://npmjs.org/package/loopback-explorer) instead.
*
* **Options**
*
* - `basePath` The basepath for your API - eg. 'http://localhost:3000'.
*
* **Example**
*
* ```js
* // enable docs
* app.docs({basePath: 'http://localhost:3000'});
* ```
*
* Run your app then navigate to
* [the API explorer](http://petstore.swagger.wordnik.com/).
* Enter your API basepath to view your generated docs.
*
* @deprecated
*/ */
app.docs = function (options) { app.docs = function (options) {
@ -255,6 +321,12 @@ app.enableAuth = function() {
* - `models` - _optional_ - an object containing `Model` definitions * - `models` - _optional_ - an object containing `Model` definitions
* - `dataSources` - _optional_ - an object containing `DataSource` 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.
*
* <a name="model-definition"></a> * <a name="model-definition"></a>
* **Model Definitions** * **Model Definitions**
* *
@ -314,7 +386,7 @@ app.enableAuth = function() {
* *
* - `connector` - **required** - the name of the [connector](#working-with-data-sources-and-connectors) * - `connector` - **required** - the name of the [connector](#working-with-data-sources-and-connectors)
* *
* * @header app.boot([options])
* @throws {Error} If config is not valid * @throws {Error} If config is not valid
* @throws {Error} If boot fails * @throws {Error} If boot fails
*/ */