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

8.8 KiB
Raw Blame History

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