loopback/docs/rest.md

#Model 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
- Model.upsert
- Model.exists
- Model.findById
- Model.find
- Model.findOne
- Model.deleteById
- Model.count
- Model.prototype.updateAttributes
- Model.prototype.reload

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


####Example Request
    curl -X POST -H "Content-Type:application/json" -d '' http://localhost:3000/locations

####Example Response


####Potential Errors
* None


###upsert


Update or create a model instance

####Definition


    PUT /locations

####Arguments
* **data**


####Example Request
    curl -X PUT -H "Content-Type:application/json" -d '' http://localhost:3000/locations

####Example Response


####Potential Errors
* None


###exists


Check the existence of a model instance by id

####Definition


    GET /locations/exists

####Arguments
* **id**


####Example Request
    curl http://localhost:3000/locations/exists/88

####Example Response

    {
        "exists": true
    }

####Potential Errors
* None


###findById


Retrieve a model instance by id

####Definition


    GET /locations/{id}

####Arguments
* **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 model instances matching the filter

####Definition


    GET /locations

####Arguments
* **filter**


####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 one model instance matching the filter


####Definition


    GET /locations/findOne

####Arguments
* **filter**


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

####Definition


    DELETE /locations/{id}

####Arguments
* **id**


####Example Request
    curl -X DELETE http://localhost:3000/locations/88

####Example Response


####Potential Errors
* None


###count


Count the number of model instances matching the where criteria

####Definition


    GET /locations/count

####Arguments
* **where**


####Example Request
    curl http://localhost:3000/locations/count

####Example Response

    {
        count: 6
    }

####Potential Errors
* None


###nearby


Find nearby locations around a given geolocation

####Definition


    GET /locations/nearby

####Arguments
* **here**
* **page**
* **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


###update


Update a model instance by id

####Definition


    PUT /locations/{id}

####Arguments
* **data**
* **id**


####Example Request
    curl -X PUT -H "Content-Type:application/json" -d '' http://localhost:3000/locations/{id}

####Example Response


####Potential Errors
* None


###reload


Reload a model instance by id

####Definition


    POST /locations/{id}/reload

####Arguments
* **id**


####Example Request
    curl -X POST -H "Content-Type:application/json" -d '' http://localhost:3000/locations/{id}/reload

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