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 #16 from strongloop/update-docs 

Update docs
This commit is contained in:
Raymond Feng 2013-08-29 23:28:53 -07:00
parent 28ef0becd4 23dc6fed2b
commit e41e0a8653
2 changed files with 169 additions and 128 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
docs/concepts.md
View File

@ -6,10 +6,9 @@
###Model
LoopBack is centered around models. A model is an object that
encapsulates data. A model is usually named after its
real life counterpart. Like its real life counterpart, a model has
some properties. Each property has a name, a type,
LoopBack is centered around models. A model is an object that encapsulates
data. A model is usually named after its real life counterpart. Like its real
life counterpart, a model has some properties. Each property has a name, a type,
and other attributes. For example,
model: Person
@ -18,9 +17,9 @@ and other attributes. For example,
- a Person model has properties such as First Name, Last Name and Birthday.
- First Name and Last Name are strings while Birthday is date.
A model can also do things as actions and behaviors. Some actions
are common to all instances of the same model while
others are specific to a given instance. For example,
A model can also do things as actions and behaviors. Some actions are common to
all instances of the same model while others are specific to a given instance.
For example,
model: Person
@ -28,26 +27,23 @@ others are specific to a given instance. For example,
- a Person model can say his/her Full Name (relying on a given instance)
- a Person model can find people by Last Name (independent of instances)
Models are the vehicle for data exchange and data representation
across different layers in LoopBack. For example, the
Person model is available as database tables, Node.js classes, REST
resources, and mobile SDK objects.
Models are the vehicle for data exchange and data representation across
different layers in LoopBack. For example, the Person model is available as
database tables, Node.js classes, REST resources, and mobile SDK objects.
When developing your mobile applications, think of models being the
"M" in your MVC framework. Models in LoopBack have
backend connectivity built in already, so that you can save data
back to your backend and call actions or functions run
When developing your mobile applications, think of models being the "M" in your
MVC framework. Models in LoopBack have backend connectivity built in already,
so that you can save data back to your backend and call actions or functions run
on the backend seamlessly from your mobile application.
###LoopBack Definition Language (LDL)
All models in LoopBack can be described as JSON objects. LoopBack
has utilized and extended JSON to define a model's properties and
structure. The JSON that is utilized to help define a model's
properties and structure or schema is called LoopBack Definition
language (LDL). LDL is a simple DSL to define data models in
JavaScript or plain JSON. The model definitions establish common
knowledge of data in LoopBack. For example,
All models in LoopBack can be described as JSON objects. LoopBack has utilized
and extended JSON to define a model's properties and structure. The JSON that is
utilized to help define a model's properties and structure or schema is called
LoopBack Definition Language (LDL). LDL is simple DSL to define data models in
JavaScript or plain JSON. The model definitions establish common knowledge of
data in LoopBack. For example,
model: Person
@ -62,26 +58,23 @@ For more information, please read [LoopBack Definition Language Guide](/loopback
###Datasources and Connectors
LoopBack allows you to connect to many sources of data and services
in the cloud and on premise in your data center.
These sources of data and services are called DataSources.
DataSources are accessed through a plugin called a Connector
in LoopBack. Plugins are highly customizable and extensible.
Unlike other mobile backend, LoopBack can leverage your existing
data and organize them in the form of models.
LoopBack allows you to connect to many sources of data and services in the cloud
and on premise in your data center. These sources of data and services are
called DataSources. DataSources are accessed through a plugin called a Connector
in LoopBack. Plugins are highly customizable and extensible. Unlike other
mobile backend, LoopBack can leverage your existing data and organize them in
the form of models.
The concept of DataSource is introduced to encapsulate business
logic to exchange data between models and various data sources.
Data sources are typically databases that provide create, retrieve,
update, and delete (CRUD) functions. LoopBack also generalize
other backend services, such as REST APIs, SOAP Web Services, and Storage Services, as data sources.
The concept of DataSource is introduced to encapsulate business logic to
exchange data between models and various data sources. Data sources are
typically databases that provide create, retrieve, update, and delete (CRUD)
functions. LoopBack also generalize other backend services, such as REST APIs,
SOAP Web Services, and Storage Services, as data sources.
Data sources are backed by connectors which implement the data
exchange logic using database drivers or other client APIs.
In general, connectors are not used directly by application code.
The DataSource class provides APIs to configure the
underlying connector and exposes functions via DataSource or model
classes.
Data sources are backed by connectors which implement the data exchange logic
using database drivers or other client APIs. In general, connectors are not used
directly by application code. The DataSource class provides APIs to configure
the underlying connector and exposes functions via DataSource or model classes.
#### LoopBack Connector Modules
@ -96,13 +89,13 @@ For more information, please read [LoopBack DataSource and Connector Guide](/loo
### REST
Everything defined in LoopBack is available to you as a REST
endpoint. For every model that is created in LoopBack, a
REST endpoint is automatically created for you. You can see and
experiment with your REST api using the [LoopBack API Explorer](http://localhost:3000/explorer/).
Everything defined in LoopBack is available to you as a REST endpoint. For
every model that is created in LoopBack, a REST endpoint is automatically
created for you. You can see and experiment with your REST api using the
[LoopBack API Explorer](http://localhost:3000/explorer/).
LoopBack also supports other protocols for your API as well. Socket.
io is another protocol that is currently being developed.
LoopBack also supports other protocols for your API as well. Socket.io is
another protocol that is currently being developed.
For more information, please read [Model REST APIs](#model-rest-api).

212
docs/rest.md
View File

@ -1,53 +1,24 @@
## REST API
LoopBack automatically binds a model to a list of HTTP endpoints that provide REST APIs for CRUD and other remote
The REST API allows clients to interact with the LoopBack models using HTTP.
The clients can be a web browser, a JavaScript program, a mobile SDK, a curl
script, or anything that can act as an HTTP client.
LoopBack automatically binds a model to a list of HTTP endpoints that provide
REST APIs for model instance data manipulations (CRUD) and other remote
operations.
### Sample Model
We'll use a simple model called `Location` (locations for rental) to illustrate
what REST APIs are exposed by LoopBack.
We use the following `Location` model as an example to illustrate generated REST APIs.
{
"name": "Location",
"options": {
"idInjection": false
},
"properties": {
"id": {
"type": "String",
"length": 20,
"id": 1
},
"street": {
"type": "String",
"required": false,
"length": 20
},
"city": {
"type": "String",
"required": false,
"length": 20
},
"zipcode": {
"type": "Number",
"required": false,
"length": 20
},
"name": {
"type": "String",
"required": false,
"length": 20
},
"geo": {
"type": "GeoPoint"
}
}
}
By default, the REST APIs are mounted to `/pluralFormOfTheModelName`, for example, `/locations`.
By default, the REST APIs are mounted to `/<pluralFormOfTheModelName>`, for
example, `/locations`, to the base URL such as http://localhost:3000/.
### CRUD remote methods
For a model backed by a data source that supports CRUD operations, you'll see
the following endpoints:
- Model.create: POST /locations
- Model.upsert: PUT /locations
- Model.exists: GET /locations/:id/exists
@ -60,15 +31,16 @@ By default, the REST APIs are mounted to `/pluralFormOfTheModelName`, for exampl
### Custom remote methods
To expose a JavaScript method as REST API, we can simply describe the method as follows:
To expose a JavaScript method as REST API, we can simply describe the method as
follows:
loopback.remoteMethod(
RentalLocation.nearby,
Location.nearby,
{
description: 'Find nearby locations around the given geo point',
description: 'Find nearby locations around the geo point',
accepts: [
{arg: 'here', type: 'GeoPoint', required: true},
{arg: 'page', type: 'Number'},
{arg: 'here', type: 'GeoPoint', required: true, description: 'geo location (lat & lng)'},
{arg: 'page', type: 'Number', description: 'number of pages (page size=10)'},
{arg: 'max', type: 'Number', description: 'max distance in miles'}
],
returns: {arg: 'locations', root: true},
@ -79,9 +51,53 @@ To expose a JavaScript method as REST API, we can simply describe the method as
The remoting is defined using the following properties:
- description: Description of the REST API
- accepts: An array of parameter description
- accepts: An array of parameters, each parameter has a name, a type, and an
optional description
- returns: Description of the return value
- http: Binding to the HTTP endpoint
- http: Binding to the HTTP endpoint, including the verb and path
### Request Format
For POST and PUT requests, the request body must be JSON, with the Content-Type
header set to application/json.
#### Encode the JSON object as query string
LoopBack uses the syntax from [node-querystring](https://github.com/visionmedia/node-querystring)
to encode JSON objects or arrays as query string. For example,
user[name][first]=John&user[email]=callback@strongloop.com
==>
{ user: { name: { first: 'John' }, email: 'callback@strongloop.com' } }
user[names][]=John&user[names][]=Mary&user[email]=callback@strongloop.com
==>
{ user: { names: ['John', 'Mary'], email: 'callback@strongloop.com' }}
items=a&items=b
==> { items: ['a', 'b'] }
For more examples, please check out [node-querystring](https://github.com/visionmedia/node-querystring/blob/master/test/parse.js)
### Response Format
The response format for all requests is a JSON object or array if present. Some
responses have an empty body.
Whether a request succeeded is indicated by the HTTP status code. A 2xx status
code indicates success, whereas a 4xx status code indicates request related
issues. 5xx status code reports server side problems.
The response for an error is in the following format:
{
"error": {
"message": "could not find a model with id 1",
"stack": "Error: could not find a model with id 1\n ...",
"statusCode": 404
}
}
###Generated APIs
@ -99,7 +115,9 @@ Create a new instance of the model and persist it into the data source
####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
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
####Example Response
@ -123,7 +141,9 @@ Update an existing model instance or insert a new one into the data source
####Example Request
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
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
####Example Response
@ -207,18 +227,56 @@ Find all instances of the model matched by filter from the data source
####Arguments
* **filter** The filter that defines where, order, fields, skip, and limit
Properties for the filter object:
- **where** `Object` { key: val, key2: {gt: 'val2'}} The search criteria
- Format: {key: val} or {key: {op: val}}
- Operations:
- gt: >
- gte: >=
- lt: <
- lte: <=
- between
- inq: IN
- nin: NOT IN
- neq: !=
- like: LIKE
- nlike: NOT LIKE
where - Object { key: val, key2: {gt: 'val2'}}
include - String, Object or Array.
order - String "key1 ASC, key2 DESC"
limit - Number The max number of items
skip - Number The number of items to be skipped
fields - Object|Array|String A list of properties to be included or excluded
['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
- **include** `String`, `Object` or `Array` Allows you to load relations of several objects and optimize numbers of requests.
- 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
- **order** `String` The sorting order
- Format: 'key1 ASC, key2 DESC'
- **limit** `Number` The maximum number of instances to be returned
- **skip** `Number` Skip the number of instances
- **offset** `Number` Alias for skip
- **fields** `Object|Array|String` The included/excluded fields
- `['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/2': A weapon by id
- '/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/nearby?here[lat]=37.587409&here[lng]=-122.338225': Locations nearby
- '/locations?filter[where][geo][near]=153.536,-28.1&filter[limit]=3': The 3 closest locations to a given geo point
- '/locations/87/inventory': The inventory for store 87
####Example Request
curl http://localhost:3000/locations
@ -266,24 +324,12 @@ Find first instance of the model matched by filter from the data source
GET /locations/findOne
####Arguments
* **filter** The filter that defines where, order, fields, skip, and limit
Properties for the filter object:
where - Object { key: val, key2: {gt: 'val2'}}
include - String, Object or Array.
order - String "key1 ASC, key2 DESC"
limit - Number The max number of items
skip - Number The number of items to be skipped
fields - Object|Array|String A list of properties to be included or excluded
['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
* **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
curl http://localhost:3000/locations/findOne?filter[where][city]=Scottsdale
####Example Response
@ -420,19 +466,21 @@ Update attributes for a model instance and persist it into the data source
####Example Request
curl -X PUT -H "Content-Type:application/json" -d '{"name': "L2"}' http://localhost:3000/locations/88
curl -X PUT -H "Content-Type:application/json" -d '{"name': "L2"}' \
http://localhost:3000/locations/88
####Example Response
####Potential Errors
* None
* 404 No instance found for the given id
###getInventory
Follow the relations from location to inventory to get a list of items for a given location
Follow the relations from location to inventory to get a list of inventory items
for a given location
####Definition
@ -440,8 +488,8 @@ Follow the relations from location to inventory to get a list of items for a giv
GET /locations/{id}/inventory
####Arguments
* **where**
* **id**
* **where** The search criteria for inventory items
* **id** The id for the location model
####Example Request