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

reorg and rewriting of first part of LoopBack guide, with new diagram

This commit is contained in:
crandmck 2013-10-10 10:53:06 -07:00
parent fb70a838a6
commit 195aaa5bf3
8 changed files with 313 additions and 499 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs.json
View File

@ -3,9 +3,9 @@
"content": [ "content": [
"docs/intro.md", "docs/intro.md",
"docs/quickstart.md", "docs/quickstart.md",
"docs/apiexplorer.md",
"docs/concepts.md", "docs/concepts.md",
"docs/cli.md", "docs/cli.md",
"docs/apiexplorer.md",
"docs/api.md", "docs/api.md",
"docs/ios.md", "docs/ios.md",
"docs/js.md", "docs/js.md",

108
docs/api-explorer-details.md Normal file
View File

@ -0,0 +1,108 @@
<!-- NOTE: This file is not currently included into the docs. Need to (a) decide if this info is important and if so (b) decide where to put it.
-->
# REST API specs
LoopBack API Explorer is built on top of the popular
[Swagger Framework](https://github.com/wordnik/swagger-core/wiki). There are two
components involved.
1. LoopBack builds up formal specifications of the REST APIs using the knowledge of
model definitions, JavaScript method declarations, and remote mappings. The
specifications are served over the following endpoints.
2. The wonderful Web UI is brought you by [Swagger UI](https://github.com/strongloop/swagger-ui).
Swagger UI is a collection of HTML, Javascript, and CSS assets that dynamically
generate beautiful documentation and sandbox from the REST API specifications.
## Resource Listing
The first part is a listing of the REST APIs.
- http://localhost:3000/swagger/resources
```javascript
{
"swaggerVersion": "1.1",
"basePath": "http://localhost:3000",
"apis": [
{
"path": "/swagger/ammo"
},
{
"path": "/swagger/customers"
},
{
"path": "/swagger/inventory"
},
{
"path": "/swagger/locations"
},
{
"path": "/swagger/weapons"
}
]
}
```
## Resource Operations
The second part describes all operations of a given model.
- http://localhost:3000/swagger/locations
```javascript
{
"swaggerVersion": "1.1",
"basePath": "http://localhost:3000",
"apis": [
{
"path": "/locations",
"operations": [
{
"httpMethod": "POST",
"nickname": "locations_create",
"responseClass": "object",
"parameters": [
{
"paramType": "body",
"name": "data",
"description": "Model instance data",
"dataType": "object",
"required": false,
"allowMultiple": false
}
],
"errorResponses": [],
"summary": "Create a new instance of the model and persist it into the data source",
"notes": ""
}
]
},
...
{
"path": "/locations/{id}",
"operations": [
{
"httpMethod": "GET",
"nickname": "locations_findById",
"responseClass": "any",
"parameters": [
{
"paramType": "path",
"name": "id",
"description": "Model id",
"dataType": "any",
"required": true,
"allowMultiple": false
}
],
"errorResponses": [],
"summary": "Find a model instance by id from the data source",
"notes": ""
}
]
},
...
]
}
```

170
docs/apiexplorer.md
View File

@ -1,159 +1,31 @@
## API Explorer ### Using the API Explorer
LoopBack helps you build APIs for mobile applications. As you follow the steps Follow these steps to explore the sample app's REST API:
to create a project and add models using the `slc lb` command line tool, REST
APIs are automatically added to your application.
Now we have a handful of REST APIs. It would be nice to see the list of APIs and
try them out without writing code. We can do that! LoopBack provides a Web based
API explorer out of the box to document and explore REST APIs for the models.
Let's give a try first.
### API Explorer UI
Step 1: Run the sample application
$ cd sls-sample-app
$ slc run app
Step 2: Open your browser and point to http://localhost:3000/explorer. You'll
see a list of REST API endpoints as illustrated below.
![Resource Listing](assets/explorer-listing.png)
1. Open your browser to http://localhost:3000/explorer. You'll see a list of REST API endpoints as illustrated below.
<img src="assets/explorer-listing.png" alt="API Explorer Listing" width="600" style="border: 1px solid gray; padding: 5px; margin: 10px;">
The endpoints are grouped by the model names. Each endpoint consists of a list The endpoints are grouped by the model names. Each endpoint consists of a list
of operations for the model. of operations for the model.
2. Click on one of the endpoint paths (such as /locations) to see available
operations for a given model. You'll see the CRUD operations mapped to HTTP verbs and paths.
<img src="assets/explorer-endpoint.png" alt="API Exlporer Endpoints" width="600" style="border: 1px solid gray; padding: 5px; margin: 10px;">
3. Click on a given operation to see the signature; for example, GET `/locations/{id}`:
<img src="assets/explorer-api.png" alt="API Spec" width="600" style="border: 1px solid gray; padding: 5px; margin: 10px;">
Notice that each operation has the HTTP verb, path, description, response model, and a list of request parameters.
4. Invoke an operation: fill in the parameters, then click the **Try it out!** button. You'll see something like this:
Step 3: Click on one of the endpoint paths (such as /locations) to see available <img src="assets/explorer-req-res.png" alt="Request/Response" width="400" style="border: 1px solid gray; padding: 5px; margin: 10px 10px 10px 100px;">
operations for a given model.
![API Endpoint](assets/explorer-endpoint.png) You can see the request URL, the JSON in the response body, and the HTTP response code and headers.
Great, now you see the CRUD operations mapped to HTTP verbs and paths. <h3>Next Steps</h3>
Step 4: Click on a given operation to see the signature To gain a deeper understanding of LoopBack and how it works, read the following sections, [Working with Models](#working-with-models) and [Working with Data Sources and Connectors](#working-with-data-sources-and-connectors).
![API Spec](assets/explorer-api.png) For information on how StrongLoop Suite provides:
Please note each operation has the HTTP verb, path, description, response model, - Out-of-the-box scalability, see
and a list of request parameters. [StrongNode](http://docs.strongloop.com/strongnode#quick-start).
- CPU profiling and path trace features, see
Step 5: Try to invoke an operation [StrongOps](http://docs.strongloop.com/strongops#quick-start).
- Mobile client APIs, see [LoopBack Client SDKs](http://docs.strongloop.com/loopback-clients/).
Fill in the parameters, and then click on `Try it out!` button.
Here we go:
![Request/Response](assets/explorer-req-res.png)
Cool, we can invoke the REST APIs without writing code!
You might be curious about the magic behind it all. Let's reveal a bit to you.
### REST API specs
LoopBack API Explorer is built on top of the popular
[Swagger Framework](https://github.com/wordnik/swagger-core/wiki). There are two
components involved.
1. LoopBack builds up formal specifications of the REST APIs using the knowledge of
model definitions, JavaScript method declarations, and remote mappings. The
specifications are served over the following endpoints.
2. The wonderful Web UI is brought you by [Swagger UI](https://github.com/strongloop/swagger-ui).
Swagger UI is a collection of HTML, Javascript, and CSS assets that dynamically
generate beautiful documentation and sandbox from the REST API specifications.
#### Resource Listing
The first part is a listing of the REST APIs.
- http://localhost:3000/swagger/resources
{
"swaggerVersion": "1.1",
"basePath": "http://localhost:3000",
"apis": [
{
"path": "/swagger/ammo"
},
{
"path": "/swagger/customers"
},
{
"path": "/swagger/inventory"
},
{
"path": "/swagger/locations"
},
{
"path": "/swagger/weapons"
}
]
}
#### Resource Operations
The second part describes all operations of a given model.
- http://localhost:3000/swagger/locations
{
"swaggerVersion": "1.1",
"basePath": "http://localhost:3000",
"apis": [
{
"path": "/locations",
"operations": [
{
"httpMethod": "POST",
"nickname": "locations_create",
"responseClass": "object",
"parameters": [
{
"paramType": "body",
"name": "data",
"description": "Model instance data",
"dataType": "object",
"required": false,
"allowMultiple": false
}
],
"errorResponses": [],
"summary": "Create a new instance of the model and persist it into the data source",
"notes": ""
}
]
},
...
{
"path": "/locations/{id}",
"operations": [
{
"httpMethod": "GET",
"nickname": "locations_findById",
"responseClass": "any",
"parameters": [
{
"paramType": "path",
"name": "id",
"description": "Model id",
"dataType": "any",
"required": true,
"allowMultiple": false
}
],
"errorResponses": [],
"summary": "Find a model instance by id from the data source",
"notes": ""
}
]
},
...
]
}
**Note: The API specifications will be enhanced in future releases to include
the model definitions.**

BIN
docs/assets/loopback-architecture.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 91 KiB

66
docs/cli.md
View File

@ -1,42 +1,48 @@
## Command Line ## Command Line Tool
The StrongLoop Suite comes bundled with a command line tool called StrongLoop StrongLoop Suite includes a command-line tool, `slc` (StrongLoop Command), for working with applications.
Command or `slc`. StrongLoop Command allows you to create boilerplate for The `slc lb` command enables you to quickly create new LoopBack applications and models with the following sub-commands:
LoopBack and other StrongNode applications.
### Commands * [workspace](#workspace): create a new workspace, essentially a container for multiple projects.
* [project](#project): create a new application.
* [model](#model): create a new model for a LoopBack application.
`slc lb` provides the following commands. For more information on the `slc` command, see [StrongLoop Control](/strongnode/#strongloop-control-slc).
#### workspace ### workspace
Initialize a workspace as a new empty directory with an optional <pre>
name. The default name is "loopback-workspace". slc lb workspace <i>wsname</i>
</pre>
```sh Creates an empty directory named _wsname_. The argument is optional; default is "loopback-workspace".
$ slc lb workspace my-loopback-workspace
```
#### project A LoopBack workspace is essentially a container for application projects. It is not required to create an application, but may be helpful for organization.
Create a LoopBack application in a new directory within the current directory ### project
using the given name. The name arg is required.
```sh <pre>
$ cd my-loopback-workspace slc lb project <i>app_name</i>
$ slc lb project my-app </pre>
$ slc run my-app
```
#### model Creates a LoopBack application called _appname_, where _appname_ is a valid JavaScript identifier.
Create a model in an existing LoopBack application. If you provide the This command creates a new directory called _appname_ in the current directory containing:
`-i` or `--interactive` flags, you will be prompted through a model * app.js
configuration. The `--data-source` flag allows you to specify the name of a * package.json
custom data. Otheriwse it will use the data source named "db". * modules directory, containing: <ul><li> app directory - contains config.json, index.js, and module.json files
</li>
<li> db directory - contains files index.js and module.json</li>
<li> docs directory - contains files config.json, index.js, and module.json; explorer directory</li></ul>
```sh ### model
$ cd my-app
$ slc lb model product
```
--- <pre>
slc lb model <i>modelname</i>
</pre>
Creates a model named _modelname_ in an existing LoopBack application.
Provide the
`-i` or `--interactive` flag to be prompted through model
configuration. Use the `--data-source` flag to specify the name of a
custom data source; default is data source named "db".

357
docs/concepts.md
View File

@ -1,123 +1,53 @@
## Concepts ## Working with Models
### Overview A LoopBack model consists of:
Before we go into all the wonderful concepts that make up LoopBack, let's first - Application data.
answer a couple of questions: - Validation rules.
- Data access capabilities.
- Business logic.
> What _is_ LoopBack? Apps use the model API to display information to the user or trigger actions
on the models to interact with backend systems. LoopBack supports both "dynamic" schema-less models and "static", schema-driven models.
- A component in [StrongLoop Suite](http://www.strongloop.com/strongloop-suite). _Dynamic models_ require only a name. The format of the data are specified completely and flexibly by the client application. Well-suited for data that originates on the client, dynamic models enable you to persist data both between sessions and between devices without involving a schema.
- A library of Node.js modules for connecting mobile apps to a variety of data
sources.
- A command line tool, `slc lb`, for generating models and entire applications
with the LoopBack library.
- A set of SDKs for native and web-based mobile clients.
> How does LoopBack work? _Static models_ require more code up front, with the format of the data specified completely in JSON. Well-suited to both existing data and large, intricate datasets, static models provide structure and
consistency to their data, preventing bugs that can result from unexpected data in the database.
- LoopBack applications are made up of three components: Here is a simple example of creating and using a model.
[Models](#models), [Data Sources/Connectors](#data-sources-and-connectors), and the
[Mobile Clients](#mobile-clients) that consume them.
- Any mobile or web app can interact with LoopBack through the Model API that are <h3>Defining a Model</h3>
backed by various data sources. The Model API is available
[locally within Node.js](#model), [remotely over REST](#rest-api), and as native
mobile SDKs for [iOS, Android, and HTML5](#mobile-clients). Using the API,
clients can query databases, store data, upload files, send emails, create push
notifications, register users, and any other behavior provided by data sources.
![concepts](assets/loopback-concepts.png "LoopBack Concepts") Consider an e-commerce app with `Product` and `Inventory` models.
A mobile client could use the `Product` model API to search through all of the
### Mobile Clients products in a database. A client could join the `Product` and `Inventory` data to
determine what products are in stock, or the `Product` model could provide a
LoopBack provides native Client SDKs to give mobile developers access to remote,
persistent data in a contextually-relevant way. The transport and marshalling of
the data is taken care of, and mobile developers can leverage all of their
existing tools (XCode, Eclipse, et al) to model their data on the client,
persisting it to the server as needed.
To achieve this, LoopBack supports both "Dynamic", schema-less Models and
"Static", schema-driven Models. (See ["Models"](#models) for more specifics and
how-tos around Model creation.)
Dynamic Models require minimal server code up front (just a name!) to set-up,
with the format of the data specified _completely_ and _flexibly_ by the client
application. Well-suited for data that _originates on the client_, mobile
developers can leverage Dynamic Models to persist data both between sessions and
between _devices_ while obviating the need for outside engineering support.
(Let's be honest - how many server programmers do you know that are _excited_
when you ask them to add a field to some schema on the server? None? That's what
we thought.)
Static Models require more code up front in an extended grammar of JSON we call
LDL, with the format of the data specified _completely_ in a _structured_ way by
the server application. Well-suited to both existing data and large, intricate
datasets, mobile developers can leverage Static Models to provide structure and
consistency to their data, preventing the multitude of bugs that can result from
unexpected data in their database. (These pesky bugs _love_ to show up in
production and ruin everyone's launch day. Stop them before they start!)
Use one strategy, or use both. Leverage them to fit your _use case_, rather than
fitting your use case to some fixed modelling strategy. The choice is yours.
### Models
> What is a Model?
A LoopBack Model consists of the following:
- Application data
- Validation rules
- Data access capabilities
- Business logic
A mobile client uses the remote API provided by Models to request any
information needed to display a useful interface to the user or trigger actions
on the models to interact with backend systems.
Let's use a simple example to explain what a model can do for you.
#### Defining a model
For example, an e-commerce app might have `Product` and `Inventory` Models.
A mobile client could use the `Product` Model API to search through all of the
Products in a database. A client could join the `Product` and `Inventory` data to
determine what products are in stock, or the `Product` Model could provide a
server-side function (or [remote method](#remote-methods)) that aggregates this server-side function (or [remote method](#remote-methods)) that aggregates this
information. information.
For example, the following code creates product and inventory models:
```js ```js
// Step 1: Create Models
var Model = require('loopback').Model; var Model = require('loopback').Model;
var Product = Model.extend('product'); var Product = Model.extend('product');
var Inventory = Model.extend('customer'); var Inventory = Model.extend('customer');
``` ```
**NOTE:** Models are _schema-less_ by default, but some data sources, such as The above code creates two dynamic models, appropriate when data is "free form." However, some data sources, such as relational databases, require schemas. Additionally, schemas are valuable to enable data exchange and to validate or sanitize data from clients; see [Sanitizing and Validating Models](#sanitizing-and-validating-models).
relational databases, _require_ schemas. Additionally, schemas are immensely
valuable for establishing the common knowledge of business data so that the data
exchange can be agreed and documented while data coming from mobile clients can
be validated and/or sanitized . See [Sanitizing and Validating Models](#sanitizing-and-validating-models)
if your application needs to connect to an RDBMS, for example.
#### Attaching to Data Sources <h3>Attaching a Model to a Data Source</h3>
Instances of a Model carry application data. But they are not very interesting A data source enables a model to access and modify data in backend system such as a relational database.
until applications can create, retrieve, update, or delete (CRUD) model instances. Attaching a model to a data source, enables the model to use the data source API. For example, as shown below, the [MongoDB Connector](http://docs.strongloop.com/loopback-connector-mongodb), mixes in a `create` method that you can use to store a new product in the database; for example:
LoopBack introduces the DataSource concept to provide the data access
capabilities to models. Attaching a Model to a DataSource gives you access to a
powerful API mixed into Models by the Connector behind a DataSource. The
[MongoDB Connector](#), for example, mixes in a `create` method that allows us
to store a new Product in the database:
```js ```js
// Step 2: Attach Data Sources // Attach data sources
var db = loopback.createDataSource({ var db = loopback.createDataSource({
connector: require('loopback-connector-mongodb') connector: require('loopback-connector-mongodb')
}); });
// Enables the Model to use the MongoDB API // Enable the model to use the MongoDB API
Product.attachTo(db); Product.attachTo(db);
// Create a new product in the database // Create a new product in the database
@ -126,17 +56,17 @@ Product.create({ name: 'widget', price: 99.99 }, function(err, widget) {
}); });
``` ```
Now the models have both data and behaviors. How can the mobile clients benefit Now the models have both data and behaviors. Next, you need to make the models available to mobile clients.
from them? We need a way to make the models available from mobile clients.
#### Exposing to Mobile Clients <h3>Exposing a Model to Mobile Clients</h3>
Models can be exposed to mobile clients using one of the remoting middlewares. To expose a model to mobile clients, use one of LoopBack's remoting middleware modules.
This example uses the `app.rest` middleware to expose the `Product` Model's API This example uses the `app.rest` middleware to expose the `Product` Model's API over REST.
over REST.
For more information on LoopBack's REST API, see [REST API](#rest-api).
```js ```js
// Step 3: Create a LoopBack Application // Step 3: Create a LoopBack application
var app = loopback(); var app = loopback();
// Use the REST remoting middleware // Use the REST remoting middleware
@ -146,20 +76,16 @@ app.use(loopback.rest());
app.model(Product); app.model(Product);
``` ```
After this, you'll have the `Product` model with CRUD functions working remotely After this, you'll have the `Product` model with create, read, update, and delete (CRUD) functions working remotely
from the mobile clients. Please note the model is schema-less till now and the from mobile clients. At this point, the model is schema-less and the data are not checked.
data are not checked.
#### Sanitizing and Validating Models <h3>Sanitizing and Validating Models</h3>
A Model can be described in plain JSON or JavaScript. The description is called A *schema* provides a description of a model written in **LoopBack Definition Language**, a specific form of JSON. Once a schema is defined for a model, the model validates and sanitizes data before passing it on to a data store such as a database. A model with a schema is referred to as a _static model_.
schema. Once a schema is defined for a Model, it will validate and sanitize data
before giving it to a Data Source. For example, the `Product` Model has a schema For example, the following code defines a schema and assigns it to the product model. The schema defines two fields (columns): **name**, a string, and **price**, a number. The field **name** is a required value.
that will not change. The example below updates the `Product` Model with a schema
written in **LoopBack Definition Language**, a well-documented flavor of JSON.
```js ```js
// Step 4: Add a Schema
var productSchema = { var productSchema = {
"name": { "type": "string", "required": true }, "name": { "type": "string", "required": true },
"price": "number" "price": "number"
@ -167,174 +93,67 @@ var productSchema = {
var Product = Model.extend('product', productSchema); var Product = Model.extend('product', productSchema);
``` ```
On one hand, If a remote client tries to save a product with extra properties A schema imposes restrictions on the model: If a remote client tries to save a product with extra properties
(e.g. `description`), those properties will be removed before saving the Model. (for example, `description`), those properties are removed before the app saves the data in the model.
On the other hand, the Model will _only_ be saved if the product contains the Also, since `name` is a required value, the model will _only_ be saved if the product contains a value for the `name` property.
required `name` property.
#### More About Models <h3>More Information</h3>
- Check out the Model [REST API](#rest-api). - Check out the model [REST API](#rest-api).
- Read the - Read the
[LoopBack Definition Language Guide](http://docs.strongloop.com/loopback-datasource-juggler#loopback-definition-language-guide). [LoopBack Definition Language Guide](http://docs.strongloop.com/loopback-datasource-juggler#loopback-definition-language-guide).
- Browse the [Node.js Model API](#model). - Browse the [Node.js model API](#model).
- Before you build your own, check out the [bundled Models](#bundled-models). - Before you build your own, check out the [bundled models](#bundled-models).
- Expose custom behavior to clients using [remote methods](#remote-methods). - Expose custom behavior to clients using [remote methods](#remote-methods).
- See how to [define relationships](#relationships) between Models. - See how to [define relationships](#relationships) between models.
### Data Sources and Connectors ## Working with Data Sources and Connectors
Now you see the power of LoopBack models. A model gets rich set of functions out Data sources encapsulate business logic to exchange data between models and various back-end systems such as
of the box with the contribution from Data Sources and Connectors. relational databases, REST APIs, SOAP web services, storage services, and so on.
Data sources generally provide create, retrieve, update, and delete (CRUD) functions.
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.
LoopBack allows you to connect to many sources of data and services both in the
cloud and on-premise in your data center. DataSources are accessed through a
plugin called a Connector in LoopBack. Plugins are highly customizable and
extensible. Unlike other mobile backends, LoopBack can leverage your existing
data and organize them in the form of models.
Models access data sources through _connectors_ that are extensible and customizable.
Connectors implement the data exchange logic using database drivers or other Connectors implement the data exchange logic using database drivers or other
client APIs. In general, connectors are not used directly by application code. client APIs. In general, application code does not use a connector directly.
The DataSource class provides APIs to configure the underlying connector and Rather, the `DataSource` class provides an API to configure the underlying connector.
exposes functions via DataSource or model classes.
#### LoopBack Connector Modules <h3> LoopBack Connectors</h3>
| Type | Package Name | LoopBack provides several connectors, with more under development.
| --------- | -------------------------------------------------------------------------------------- |
| Memory | [Built-in](https://github.com/strongloop/loopback-datasource-juggler) |
| MongoDB | [loopback-connector-mongodb](https://github.com/strongloop/loopback-connector-mongodb) |
| Oracle | [loopback-connector-oracle](https://github.com/strongloop/loopback-connector-oracle) |
| REST | [loopback-connector-rest](https://github.com/strongloop/loopback-connector-rest) |
For more information, please read the [LoopBack DataSource and Connector Guide](/loopback-datasource-juggler/#loopback-datasource-and-connector-guide). <table style="
margin-left: 1em;
### REST border: solid 1px #AAAAAA;
border-collapse: collapse;
Functions defined in LoopBack Models can be made available as a REST background-color: #F9F9F9;
endpoint. You can see and experiment with _your_ REST api using the font-size: 90%;
[LoopBack API Explorer](http://localhost:3000/explorer/). empty-cells:show;" border="1" cellpadding="5">
<thead>
LoopBack also supports other protocols for your API as well. Socket.io is <tr style="background-color: #C7C7C7;">
another protocol that is currently being developed. <th>Connector</th>
<th>GitHub Module</th>
For more information, please read [Model REST APIs](#model-rest-api). </tr>
</thead>
### Remoting <tbody>
<tr>
With LoopBack you can add whatever functionality you like either <td><a href="/loopback-datasource-juggler/">Memory</a></td>
by yourself or leveraging functionality from other open source <td>Built-in to <a href="https://github.com/strongloop/loopback-datasource-juggler">loopback-datasource-juggler</a></td>
modules from the community. The ability to "mix in" behaviors are </tr>
available through the inherent power of Javascript's less resrictive <tr>
inheritance model. <td><a href="/loopback-connector-mongodb/">MongoDB</a></td>
<td><a href="https://github.com/strongloop/loopback-connector-mongodb">loopback-connector-mongodb</a></td>
LoopBack takes this one step further by allowing you to seamlessly </tr>
invoke server side code running in LoopBack in the backend from the <tr>
your client on the front end. <td><a href="/loopback-connector-oracle/">Oracle</a></td>
<td><a href="https://github.com/strongloop/loopback-connector-oracle">loopback-connector-oracle</a></td>
For more information, please read the [Remoting Guide](/strong-remoting). </tr>
<tr>
### The Big Picture <td><a href="/loopback-connector-rest/">REST</a></td>
<td><a href="https://github.com/strongloop/loopback-connector-rest">loopback-connector-rest</a></td>
LoopBack's overall representation is illustrated below through its </tr>
runtime sub-components: </tbody>
</table>
- Mobile Clients
- API Gateway - ***Coming Soon***
- API Server
- Enterprise Connectors
As well as its management sub-components:
- Editor - ***Coming Soon***
- Admin Console - ***Coming Soon***
- LoopBack Node.js API
- Repository/Registry
![loopback_overview](assets/loopback_ov.png "LoopBack Overview")
At first glance, LoopBack looks like just any other API tier. But
looks can be deceiving. Here are some key differentiators that make
Loopback stand out as an api tier built for mobile:
1. Model APIS are surfaced over REST without writing code
2. The Datasource Juggler is a modern ORM that supports
not only traditional RDBMS, but also noSQL and services
3. As a mobile backend as a service (mBaaS) we help you leverage
valuable existing data in your mobile app as well dynamically create
new schema or schema-less data
<h4> Mobile clients </h4>
We're putting a lot of effort into building flexibility and
functionality into our mobile client SDKs. The ultimate goal is to
preserve what's familiar to the mobile developer in their native
platform and empower them with seamelss backend functionality.
Mobile clients call into LoopBack APIs surfaced by [strong-remoting](http://docs.strongloop.com/strong-remoting), a pluggable transport
layer that supports surfacing backend APIs over REST, WebSockets,
and other transports.
<h4> API Gateway </h4>
The first line of defense and entry is the API gateway. This
sub-component of LoopBack acts as a reverse-proxy to the rest of
LoopBack. It provides OAuth2 based security, will mediate between
multiple data formats and acts as a quality of service layer for your
API providing instrumentation and other aspect level functionality.
<h4> API Server </h4>
The core of LoopBack is the API Server where models are registered
and hosted during runtime. Models are automatically exposed through a REST endpoint.
The API server also will run batch processes or scheduled jobs as a
mobile backend for functions like mass push notifications.
<h4> Enterprise Connectors </h4>
LoopBack lets you leveratge existing data and services that you need
in your mobile apps just as you do in your web apps. LoopBack has a
layer of abstraction provided by the DataSource Juggler so that all
you need to worry about is your model. The Datasource Juggler
accesses the underlying [datasources](http://docs.strongloop.com/loopback/#data-sources-and-connectors) through Enterprise
Connectors.
<h4> Editor </h4>
LoopBack comes with a rich set of [Node.js based APIs](http://docs.strongloop.com/loopback/#nodejs-api).
The editor is a web based GUI that makes it even easier to define,
configure and manage your mobile apps and models without having to
write code. The editor will also facilitate the process of
[discovering models](http://docs.strongloop.com/loopback/#datasourcediscovermodeldefinitionsusername-fn) and [schemas](http://docs.strongloop.com/loopback/#datasourcediscoverschemaowner-name-fn)
from datasources to give you a headstart on building your app.
<h4> Admin Console </h4>
Each LoopBack development environment is fully self contained. When
working in the enterprise, there is a need to distribute work much
like how distributed source control systems like `git` have risen and
evolved. When combining the work output from multiple LoopBack
development environments into a single enterprise runtime, the Admin
Console helps with merging and maintaining configuration as well as
deployment.
<h4> Repository </h4> For more information, see the [LoopBack DataSource and Connector Guide](/loopback-datasource-juggler/#loopback-datasource-and-connector-guide).
All development in LoopBack ends up as metadata that's stored in JSON
config files. Config files are distributed, merged and
consolidated centrally into the Repository. The Repository is
centrally maintained by an admin through the [Admin
Console](http://docs.strongloop.com/loopback#admin-console) where
policies like security are defined and configured.
<h4> LoopBack Node.js API </h4>
All manipulation of the metadata that constitutes the entire runtime
of the mobile API is done through an internal Node.js API. In the
spirit of truly "eating our own dog food" - the API powers the
editor and any other tools that are included with LoopBack.
---

33
docs/intro.md
View File

@ -1,11 +1,30 @@
# LoopBack <h1> LoopBack</h1>
LoopBack, part of the StrongLoop Suite, is a mobile backend framework that can run in the cloud or on your own servers. LoopBack is a mobile backend framework that you can run in the cloud or on-premises.
It is built on [StrongNode](http://strongloop.com/strongloop-suite/strongnode/) and open-source Node.js modules, so It is built on [StrongNode](http://strongloop.com/strongloop-suite/strongnode/) and open-source Node.js modules. For more information on the advantages of using LoopBack, see [StrongLoop | LoopBack](http://strongloop.com/strongloop-suite/loopback/).
it is highly extensible and familiar to developers already using Node.
For more information on the advantages of using LoopBack, see To gain a basic understanding of key LoopBack concepts, read the following [Overview](#overview) section. Then, dive right into creating an app in [Quick Start](#quick-start).
[StrongLoop / LoopBack](http://strongloop.com/strongloop-suite/loopback/).
## Overview
LoopBack consists of:
* A library of Node.js modules for connecting mobile apps to data sources such as databases and REST APIs.
* A command line tool, `slc lb`, for creating and working with LoopBack applications.
* Client SDKs for native and web-based mobile clients.
As illustrated in the diagram below, a LoopBack application has three components:
+ **Models** that represent business data and behavior.
+ **Data sources and connectors**. Data sources are databases or other backend services such as REST APIs, SOAP web services, or storage services. Connectors provide apps access to enterprise data sources such as Oracle, MySQL, and MongoDB.
+ **Mobile clients** using the LoopBack client SDKs.
<img src="./assets/loopback-architecture.png" width="600" alt="StrongLoop Architecture"></img>
An app interacts with data sources through the LoopBack model API, available
[locally within Node.js](#model), [remotely over REST](#rest-api), and via native client
APIs for [iOS, Android, and HTML5](#mobile-clients). Using the API, apps can query databases, store data, upload files, send emails, create push notifications, register users, and perform other actions provided by data sources.
Mobile clients can call LoopBack server APIs directly using [Strong Remoting](/strong-remoting), a pluggable transport
layer that enables you to provide backend APIs over REST, WebSockets, and other transports.
---

76
docs/quickstart.md
View File

@ -1,59 +1,49 @@
###Quick Start ##Quick Start
<h4>Step 1</h4> This section will get you up and running with LoopBack and the StrongLoop sample app in just a few minutes.
> Install [StrongLoop Suite](http://www.strongloop.com/get-started) ### Prerequisites
<h4>Step 2</h4> You must have the `git` command-line tool installed to run the sample application.
If needed, download it at <http://git-scm.com/downloads> and install it.
> Setup the **StrongLoop Suite Sample App**. On Linux systems, you must have root privileges to write to `/usr/share`.
**NOTE**: If you're using Windows or OSX and don't have a C compiler (Visual C++ on Windows or XCode on OSX) and command-line "make" tools installed, you will see errors such as these:
```sh
xcode-select: Error: No Xcode is selected. Use xcode-select -switch <path-to-xcode>,
or see the xcode-select manpage (man xcode-select) for further information.
...
Unable to load native module uvmon; some features may be unavailable without compiling it.
memwatch must be installed to use the instances feature
StrongOps not configured to monitor. Please refer to http://docs.strongloop.com/strong-agent for usage.
```
You will still be able to run the sample app, but StrongOps will not be able to collect certain statistics.
### Creating and Running the Sample App
Follow these steps to run the LoopBack sample app:
1. If you have not already done so, download and install [StrongLoop Suite](http://www.strongloop.com/get-started) or set up your cloud development platform.
2. Setup the StrongLoop Suite sample app with this command.
```sh ```sh
$ slc example $ slc example
``` ```
This command clones the sample app into a new directory
The command above takes care of cloning the sample app into a new directory named `sls-sample-app` and installs all of its dependencies.
named `sls-sample-app` and installing all of its dependencies. 3. Run the sample application by entering this command:
<h4>Step 3</h4>
> Run the sample application.
```sh ```sh
$ cd sls-sample-app $ cd sls-sample-app
$ slc run app $ slc run app
``` ```
4. To see the app running in a browser, open <http://localhost:3000>. The app homepage lists sample requests you can make against the LoopBack REST API. Click the **GET** buttons to see the JSON data returned.
<h4>Step 4</h4> ### About the sample app
> Open the app in a browser. The StrongLoop sample is a mobile app for "Blackpool," an imaginary military equipment rental dealer with outlets in major cities around the world. It enables customers (military commanders) to rent weapons and buy ammunition from Blackpool using their mobile phones. The app displays a map of nearby rental locations and see currently available weapons, which you can filter by price, ammo type and distance. Then, you can use the app to reserve the desired weapons and ammo.
The sample app should now be running at <a href="http://localhost:3000" target="_blank">http://localhost:3000</a>. The homepage of Note that the sample app is the backend functionality only; that is, the app has a REST API, but no client app or UI to consume the interface.
the sample app lists several sample requests you can make against the LoopBack
REST API.
<a href="http://localhost:3000" class="status btn btn-primary" target="_blank"> For more details on the sample app, see [StrongLoop sls-sample-app](https://github.com/strongloop/sls-sample-app) in GitHub.
View the Sample App</a>
<h4>Step 5</h4>
> Explore the REST API
To browse all the sample app's REST APIs,
[open the API explorer](http://localhost:3000/explorer)
<a href="http://localhost:3000/explorer" class="status btn btn-primary">View the
API Explorer</a>
<h4>Next Steps</h4>
> Check out the rest of the StrongLoop Suite.
- To see how to consume the API from mobile clients, check out the [Getting Started](#getting-started) guide.
- To see the out-of-the-box scaling capability of the Suite, check out the
[StrongNode Quick Start Guide](http://docs.strongloop.com/strongnode#quick-start).
- To see the provided CPU profiling and path trace features, check out the
[StrongOps Quick Start Guide](http://docs.strongloop.com/strongops#quick-start).
---