Skip to content

Commit 195aaa5

Browse files
author
crandmck
committed
reorg and rewriting of first part of LoopBack guide, with new diagram
1 parent fb70a83 commit 195aaa5

8 files changed

+314
-500
lines changed

‎docs.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,9 @@
33
"content": [
44
"docs/intro.md",
55
"docs/quickstart.md",
6+
"docs/apiexplorer.md",
67
"docs/concepts.md",
78
"docs/cli.md",
8-
"docs/apiexplorer.md",
99
"docs/api.md",
1010
"docs/ios.md",
1111
"docs/js.md",

‎docs/api-explorer-details.md

+108
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
<!-- 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.
2+
3+
-->
4+
5+
# REST API specs
6+
7+
LoopBack API Explorer is built on top of the popular
8+
[Swagger Framework](https://github.com/wordnik/swagger-core/wiki). There are two
9+
components involved.
10+
11+
1. LoopBack builds up formal specifications of the REST APIs using the knowledge of
12+
model definitions, JavaScript method declarations, and remote mappings. The
13+
specifications are served over the following endpoints.
14+
15+
2. The wonderful Web UI is brought you by [Swagger UI](https://github.com/strongloop/swagger-ui).
16+
Swagger UI is a collection of HTML, Javascript, and CSS assets that dynamically
17+
generate beautiful documentation and sandbox from the REST API specifications.
18+
19+
## Resource Listing
20+
The first part is a listing of the REST APIs.
21+
22+
- http://localhost:3000/swagger/resources
23+
24+
```javascript
25+
{
26+
"swaggerVersion": "1.1",
27+
"basePath": "http://localhost:3000",
28+
"apis": [
29+
{
30+
"path": "/swagger/ammo"
31+
},
32+
{
33+
"path": "/swagger/customers"
34+
},
35+
{
36+
"path": "/swagger/inventory"
37+
},
38+
{
39+
"path": "/swagger/locations"
40+
},
41+
{
42+
"path": "/swagger/weapons"
43+
}
44+
]
45+
}
46+
```
47+
48+
## Resource Operations
49+
The second part describes all operations of a given model.
50+
51+
- http://localhost:3000/swagger/locations
52+
53+
```javascript
54+
{
55+
"swaggerVersion": "1.1",
56+
"basePath": "http://localhost:3000",
57+
"apis": [
58+
{
59+
"path": "/locations",
60+
"operations": [
61+
{
62+
"httpMethod": "POST",
63+
"nickname": "locations_create",
64+
"responseClass": "object",
65+
"parameters": [
66+
{
67+
"paramType": "body",
68+
"name": "data",
69+
"description": "Model instance data",
70+
"dataType": "object",
71+
"required": false,
72+
"allowMultiple": false
73+
}
74+
],
75+
"errorResponses": [],
76+
"summary": "Create a new instance of the model and persist it into the data source",
77+
"notes": ""
78+
}
79+
]
80+
},
81+
...
82+
{
83+
"path": "/locations/{id}",
84+
"operations": [
85+
{
86+
"httpMethod": "GET",
87+
"nickname": "locations_findById",
88+
"responseClass": "any",
89+
"parameters": [
90+
{
91+
"paramType": "path",
92+
"name": "id",
93+
"description": "Model id",
94+
"dataType": "any",
95+
"required": true,
96+
"allowMultiple": false
97+
}
98+
],
99+
"errorResponses": [],
100+
"summary": "Find a model instance by id from the data source",
101+
"notes": ""
102+
}
103+
]
104+
},
105+
...
106+
]
107+
}
108+
```

‎docs/apiexplorer.md

+21-149
Original file line numberDiff line numberDiff line change
@@ -1,159 +1,31 @@
1-
## API Explorer
1+
### Using the API Explorer
22

3-
LoopBack helps you build APIs for mobile applications. As you follow the steps
4-
to create a project and add models using the `slc lb` command line tool, REST
5-
APIs are automatically added to your application.
6-
7-
Now we have a handful of REST APIs. It would be nice to see the list of APIs and
8-
try them out without writing code. We can do that! LoopBack provides a Web based
9-
API explorer out of the box to document and explore REST APIs for the models.
10-
11-
Let's give a try first.
12-
13-
### API Explorer UI
14-
15-
Step 1: Run the sample application
16-
17-
$ cd sls-sample-app
18-
$ slc run app
19-
20-
21-
Step 2: Open your browser and point to http://localhost:3000/explorer. You'll
22-
see a list of REST API endpoints as illustrated below.
23-
24-
![Resource Listing](assets/explorer-listing.png)
3+
Follow these steps to explore the sample app's REST API:
254

5+
1. Open your browser to http://localhost:3000/explorer. You'll see a list of REST API endpoints as illustrated below.
6+
<img src="assets/explorer-listing.png" alt="API Explorer Listing" width="600" style="border: 1px solid gray; padding: 5px; margin: 10px;">
267
The endpoints are grouped by the model names. Each endpoint consists of a list
278
of operations for the model.
9+
2. Click on one of the endpoint paths (such as /locations) to see available
10+
operations for a given model. You'll see the CRUD operations mapped to HTTP verbs and paths.
11+
<img src="assets/explorer-endpoint.png" alt="API Exlporer Endpoints" width="600" style="border: 1px solid gray; padding: 5px; margin: 10px;">
12+
3. Click on a given operation to see the signature; for example, GET `/locations/{id}`:
13+
<img src="assets/explorer-api.png" alt="API Spec" width="600" style="border: 1px solid gray; padding: 5px; margin: 10px;">
14+
Notice that each operation has the HTTP verb, path, description, response model, and a list of request parameters.
15+
4. Invoke an operation: fill in the parameters, then click the **Try it out!** button. You'll see something like this:
2816

29-
Step 3: Click on one of the endpoint paths (such as /locations) to see available
30-
operations for a given model.
31-
32-
![API Endpoint](assets/explorer-endpoint.png)
33-
34-
Great, now you see the CRUD operations mapped to HTTP verbs and paths.
35-
36-
Step 4: Click on a given operation to see the signature
37-
38-
![API Spec](assets/explorer-api.png)
39-
40-
Please note each operation has the HTTP verb, path, description, response model,
41-
and a list of request parameters.
42-
43-
Step 5: Try to invoke an operation
44-
45-
Fill in the parameters, and then click on `Try it out!` button.
46-
47-
Here we go:
48-
49-
![Request/Response](assets/explorer-req-res.png)
50-
51-
Cool, we can invoke the REST APIs without writing code!
52-
53-
You might be curious about the magic behind it all. Let's reveal a bit to you.
54-
55-
### REST API specs
56-
57-
LoopBack API Explorer is built on top of the popular
58-
[Swagger Framework](https://github.com/wordnik/swagger-core/wiki). There are two
59-
components involved.
60-
61-
1. LoopBack builds up formal specifications of the REST APIs using the knowledge of
62-
model definitions, JavaScript method declarations, and remote mappings. The
63-
specifications are served over the following endpoints.
64-
65-
2. The wonderful Web UI is brought you by [Swagger UI](https://github.com/strongloop/swagger-ui).
66-
Swagger UI is a collection of HTML, Javascript, and CSS assets that dynamically
67-
generate beautiful documentation and sandbox from the REST API specifications.
68-
69-
#### Resource Listing
70-
The first part is a listing of the REST APIs.
71-
72-
- http://localhost:3000/swagger/resources
73-
74-
75-
{
76-
"swaggerVersion": "1.1",
77-
"basePath": "http://localhost:3000",
78-
"apis": [
79-
{
80-
"path": "/swagger/ammo"
81-
},
82-
{
83-
"path": "/swagger/customers"
84-
},
85-
{
86-
"path": "/swagger/inventory"
87-
},
88-
{
89-
"path": "/swagger/locations"
90-
},
91-
{
92-
"path": "/swagger/weapons"
93-
}
94-
]
95-
}
17+
<img src="assets/explorer-req-res.png" alt="Request/Response" width="400" style="border: 1px solid gray; padding: 5px; margin: 10px 10px 10px 100px;">
9618

97-
#### Resource Operations
98-
The second part describes all operations of a given model.
19+
You can see the request URL, the JSON in the response body, and the HTTP response code and headers.
9920

100-
- http://localhost:3000/swagger/locations
21+
<h3>Next Steps</h3>
10122

23+
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).
10224

103-
{
104-
"swaggerVersion": "1.1",
105-
"basePath": "http://localhost:3000",
106-
"apis": [
107-
{
108-
"path": "/locations",
109-
"operations": [
110-
{
111-
"httpMethod": "POST",
112-
"nickname": "locations_create",
113-
"responseClass": "object",
114-
"parameters": [
115-
{
116-
"paramType": "body",
117-
"name": "data",
118-
"description": "Model instance data",
119-
"dataType": "object",
120-
"required": false,
121-
"allowMultiple": false
122-
}
123-
],
124-
"errorResponses": [],
125-
"summary": "Create a new instance of the model and persist it into the data source",
126-
"notes": ""
127-
}
128-
]
129-
},
130-
...
131-
{
132-
"path": "/locations/{id}",
133-
"operations": [
134-
{
135-
"httpMethod": "GET",
136-
"nickname": "locations_findById",
137-
"responseClass": "any",
138-
"parameters": [
139-
{
140-
"paramType": "path",
141-
"name": "id",
142-
"description": "Model id",
143-
"dataType": "any",
144-
"required": true,
145-
"allowMultiple": false
146-
}
147-
],
148-
"errorResponses": [],
149-
"summary": "Find a model instance by id from the data source",
150-
"notes": ""
151-
}
152-
]
153-
},
154-
...
155-
]
156-
}
25+
For information on how StrongLoop Suite provides:
15726

158-
**Note: The API specifications will be enhanced in future releases to include
159-
the model definitions.**
27+
- Out-of-the-box scalability, see
28+
[StrongNode](http://docs.strongloop.com/strongnode#quick-start).
29+
- CPU profiling and path trace features, see
30+
[StrongOps](http://docs.strongloop.com/strongops#quick-start).
31+
- Mobile client APIs, see [LoopBack Client SDKs](http://docs.strongloop.com/loopback-clients/).

‎docs/assets/loopback-architecture.png

91.2 KB
Loading

‎docs/cli.md

+36-30
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,48 @@
1-
## Command Line
1+
## Command Line Tool
22

3-
The StrongLoop Suite comes bundled with a command line tool called StrongLoop
4-
Command or `slc`. StrongLoop Command allows you to create boilerplate for
5-
LoopBack and other StrongNode applications.
3+
StrongLoop Suite includes a command-line tool, `slc` (StrongLoop Command), for working with applications.
4+
The `slc lb` command enables you to quickly create new LoopBack applications and models with the following sub-commands:
65

7-
### Commands
6+
* [workspace](#workspace): create a new workspace, essentially a container for multiple projects.
7+
* [project](#project): create a new application.
8+
* [model](#model): create a new model for a LoopBack application.
89

9-
`slc lb` provides the following commands.
10+
For more information on the `slc` command, see [StrongLoop Control](/strongnode/#strongloop-control-slc).
1011

11-
#### workspace
12+
### workspace
1213

13-
Initialize a workspace as a new empty directory with an optional
14-
name. The default name is "loopback-workspace".
14+
<pre>
15+
slc lb workspace <i>wsname</i>
16+
</pre>
1517

16-
```sh
17-
$ slc lb workspace my-loopback-workspace
18-
```
18+
Creates an empty directory named _wsname_. The argument is optional; default is "loopback-workspace".
1919

20-
#### project
20+
A LoopBack workspace is essentially a container for application projects. It is not required to create an application, but may be helpful for organization.
2121

22-
Create a LoopBack application in a new directory within the current directory
23-
using the given name. The name arg is required.
22+
### project
2423

25-
```sh
26-
$ cd my-loopback-workspace
27-
$ slc lb project my-app
28-
$ slc run my-app
29-
```
24+
<pre>
25+
slc lb project <i>app_name</i>
26+
</pre>
3027

31-
#### model
32-
Create a model in an existing LoopBack application. If you provide the
33-
`-i` or `--interactive` flags, you will be prompted through a model
34-
configuration. The `--data-source` flag allows you to specify the name of a
35-
custom data. Otheriwse it will use the data source named "db".
28+
Creates a LoopBack application called _appname_, where _appname_ is a valid JavaScript identifier.
29+
This command creates a new directory called _appname_ in the current directory containing:
30+
* app.js
31+
* package.json
32+
* modules directory, containing: <ul><li> app directory - contains config.json, index.js, and module.json files
33+
</li>
34+
<li> db directory - contains files index.js and module.json</li>
35+
<li> docs directory - contains files config.json, index.js, and module.json; explorer directory</li></ul>
3636

37-
```sh
38-
$ cd my-app
39-
$ slc lb model product
40-
```
37+
### model
4138

42-
---
39+
<pre>
40+
slc lb model <i>modelname</i>
41+
</pre>
42+
43+
Creates a model named _modelname_ in an existing LoopBack application.
44+
45+
Provide the
46+
`-i` or `--interactive` flag to be prompted through model
47+
configuration. Use the `--data-source` flag to specify the name of a
48+
custom data source; default is data source named "db".

0 commit comments

Comments
 (0)