loopback/rest.md at 8e679d092752a09d7fe4e4ad865678d470261fd9

12 KiB

Raw Blame History

REST API

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.

We'll use a simple model called Location (locations for rental) to illustrate what REST APIs are exposed by LoopBack.

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
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(
  Location.nearby,
  {
    description: 'Find nearby locations around the geo point',
    accepts: [
      {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},
    http: {verb: 'POST', path: '/nearby'}
  }
);

The remoting is defined using the following properties:

description: Description of the REST API
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, 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 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

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

###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 { "id": "96", "street": "107 S B St", "city": "San Mateo", "zipcode": 94401, "name": "L1", "geo": { "lat": 37.5670042, "lng": -122.3240212 } }

####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

#####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

#####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

####Example Response

#####Insert { "id": "98", "street": "107 S B St", "city": "San Mateo", "zipcode": 94401, "name": "L1", "geo": { "lat": 37.5670042, "lng": -122.3240212 } }

#####Update { "id": "98", "street": "107 S B St", "city": "San Mateo", "zipcode": 94401, "name": "L4" }

####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/88/exists

####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

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
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?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.

####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. It's same as find's filter argument. Please see find for more details.

####Example Request curl http://localhost:3000/locations/findOne?filter%5Bwhere%5D%5Bcity%5D=Scottsdale

####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

#####Count without where curl http://localhost:3000/locations/count

#####Count with a where filter curl http://localhost:3000/locations/count?where%5bcity%5d=Burlingame

####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%5Blat%5D=37.587409&here%5Blng%5D=-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 { "id": "88", "street": "390 Lang Road", "city": "Burlingame", "zipcode": 94010, "name": "L2", "geo": { "lat": 37.5874391, "lng": -122.3381437 }, "state": "CA" }

####Potential 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

####Example Response

[
  {
    "productId": "2",
    "locationId": "88",
    "available": 10,
    "total": 10
  },
  {
    "productId": "3",
    "locationId": "88",
    "available": 1,
    "total": 1
  }
]

####Potential Errors

None

12 KiB Raw Blame History

REST API

CRUD remote methods

Custom remote methods

Request Format

Encode the JSON object as query string

Response Format

12 KiB

Raw Blame History