473 lines
8.8 KiB
Markdown
473 lines
8.8 KiB
Markdown
## REST API
|
|
|
|
LoopBack automatically binds a model to a list of HTTP endpoints that provide REST APIs for CRUD and other remote
|
|
operations.
|
|
|
|
### Sample Model
|
|
|
|
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`.
|
|
|
|
### CRUD remote methods
|
|
|
|
- Model.create: POST /locations
|
|
- Model.upsert: PUT /locations
|
|
- Model.exists: GET /locations/:id/exists
|
|
- Model.findById: GET /locations/:id
|
|
- Model.find: GET /locations
|
|
- Model.findOne: GET /locations/findOne
|
|
- Model.deleteById: DELETE /locations/:id
|
|
- Model.count: GET /locations/count
|
|
- Model.prototype.updateAttributes: PUT /locations/:id
|
|
|
|
### Custom remote methods
|
|
|
|
To expose a JavaScript method as REST API, we can simply describe the method as follows:
|
|
|
|
loopback.remoteMethod(
|
|
RentalLocation.nearby,
|
|
{
|
|
description: 'Find nearby locations around the given geo point',
|
|
accepts: [
|
|
{arg: 'here', type: 'GeoPoint', required: true},
|
|
{arg: 'page', type: 'Number'},
|
|
{arg: 'max', type: 'Number', description: 'max distance in miles'}
|
|
],
|
|
returns: {arg: 'locations', root: true},
|
|
http: {verb: 'POST', path: '/nearby'}
|
|
}
|
|
);
|
|
|
|
The remoting is defined using the following properties:
|
|
|
|
- description: Description of the REST API
|
|
- accepts: An array of parameter description
|
|
- returns: Description of the return value
|
|
- http: Binding to the HTTP endpoint
|
|
|
|
###Generated APIs
|
|
|
|
|
|
###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
|
|
|
|
####Example Response
|
|
|
|
|
|
####Potential 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
|
|
|
|
|
|
####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
|
|
|
|
####Example Response
|
|
|
|
|
|
####Potential 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/exists/88
|
|
|
|
####Example Response
|
|
|
|
{
|
|
"exists": true
|
|
}
|
|
|
|
####Potential 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
|
|
|
|
####Example Response
|
|
|
|
{
|
|
"id": "88",
|
|
"street": "390 Lang Road",
|
|
"city": "Burlingame",
|
|
"zipcode": 94010,
|
|
"name": "Bay Area Firearms",
|
|
"geo": {
|
|
"lat": 37.5874391,
|
|
"lng": -122.3381437
|
|
}
|
|
}
|
|
|
|
####Potential Errors
|
|
* None
|
|
|
|
|
|
###find
|
|
|
|
|
|
Find all instances of the model matched by filter from the data source
|
|
|
|
####Definition
|
|
|
|
|
|
GET /locations
|
|
|
|
####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
|
|
|
|
####Example Request
|
|
curl http://localhost:3000/locations
|
|
|
|
####Example 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
|
|
}
|
|
}
|
|
]
|
|
|
|
####Potential 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
|
|
|
|
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
|
|
|
|
|
|
####Example Request
|
|
curl http://localhost:3000/locations/findOne
|
|
|
|
####Example Response
|
|
|
|
{
|
|
"id": "87",
|
|
"street": "7153 East Thomas Road",
|
|
"city": "Scottsdale",
|
|
"zipcode": 85251,
|
|
"name": "Phoenix Equipment Rentals",
|
|
"geo": {
|
|
"lat": 33.48034450000001,
|
|
"lng": -111.9271738
|
|
}
|
|
}
|
|
|
|
####Potential 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
|
|
|
|
####Example Response
|
|
|
|
|
|
####Potential 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
|
|
curl http://localhost:3000/locations/count
|
|
|
|
####Example Response
|
|
|
|
{
|
|
count: 6
|
|
}
|
|
|
|
####Potential 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[lat]=37.587409&here[lng]=-122.338225
|
|
|
|
####Example 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
|
|
}
|
|
}
|
|
]
|
|
|
|
####Potential 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
|
|
|
|
####Example Response
|
|
|
|
|
|
####Potential Errors
|
|
* None
|
|
|
|
|
|
###getInventory
|
|
|
|
|
|
Follow the relations from location to inventory to get a list of items for a given location
|
|
|
|
####Definition
|
|
|
|
|
|
GET /locations/{id}/inventory
|
|
|
|
####Arguments
|
|
* **where**
|
|
* **id**
|
|
|
|
|
|
####Example Request
|
|
curl http://localhost:3000/locations/88/inventory
|
|
|
|
####Example Response
|
|
|
|
[
|
|
{
|
|
"productId": "2",
|
|
"locationId": "88",
|
|
"available": 10,
|
|
"total": 10
|
|
},
|
|
{
|
|
"productId": "3",
|
|
"locationId": "88",
|
|
"available": 1,
|
|
"total": 1
|
|
}
|
|
]
|
|
|
|
####Potential Errors
|
|
* None
|
|
|
|
|
|
|
|
|