PersistedModel REST API

Overview

PersistedModel is the base class for models connected to persistent data sources such as databases and is also the base class for all built-in models (except Email). It provides all the standard create, read, update, and delete (CRUD) operations and exposes REST endpoints for them.

By default, LoopBack uses /api as the URI root for the REST API. You can change this by changing the restApiRoot property in the application /server/config.json file. See config.json for more information.

Model REST API endpoints are generally the plural form of the model name. By default this is simply the name with an "s" appended. For example, if the model is "car" then "cars" is the plural form. You can customize the plural form in the model definition JSON file.

Create model instance

Create a new instance of the model and persist it to the data source.

POST /modelName

Arguments

• Form data - Model instance data. Can be JSON representing a single model instance or an array of model instances.

Example

Request URL: POST http://localhost:3000/api/locations

Request body: {"name": "L1", "street": "107 S B St", "city": "San Mateo", "zipcode": "94401"}

Response status code: 200

Response body:

{
 "id": "96",
 "street": "107 S B St",
 "city": "San Mateo",
 "zipcode": 94401,
 "name": "L1"
}

Update / insert instance

Update an existing model instance or insert a new one into the data source. The update will override any specified attributes in the request data object. It won’t remove existing ones unless the value is set to null.

Performs upsert to detect if there is a matching instance. If not, then inserts (creates) a new instance. If there is a matching instance, updates it.

PUT /modelName

Arguments

• Form data - model instance data in JSON format.

Examples

Insert

Request URL: PUT http://localhost:3000/api/locations

Request body: {"name": "L1", "street": "107 S B St", "city": "San Mateo", "zipcode": "94401"}

Response status code: 200

Response body:

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

Update

Request URL: PUT http://localhost:3000/api/locations

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

Response status code: 200

Response body:

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

Check instance existence

Check whether a model instance exists by ID in the data source.

GET /modelName/modelID/exists

Arguments

• modelID - model instance ID

Example

Request URL: GET http://localhost:3000/api/locations/88/exists

Response status code: 200

Response body:

{"exists": true}

Find instance by ID

Find a model instance by ID from the data source.

GET /modelName/modelID?filter=[filterType1]=val1&filter[filterType2]=val2...

See also Accessing related models for an example of fetching data from related models.

Arguments

• modelID - Model instance ID
• filterType1, filterType2, and so on, are the filter types. This operation supports only include and fields filters. See Include filter and Fields filter for more information.
• val1, val2 are the corresponding values.

Example

Request URL: GET http://localhost:3000/api/locations/88

Response status code: 200

Response body:

{
 "id": 88,
 "street": "390 Lang Road",
 "city": "Burlingame",
 "zipcode": 94010,
 "name": "Bay Area Firearms"
}

Find matching instances

Find all instances of the model matched by filter from the data source.

GET /modelName?filter=[filterType1]=val1&filter[filterType2]=val2...

Arguments

Pass the arguments as the value of the filter HTTP query parameters, where:

• filterType1, filterType2, and so on, are the filter types.
• val1, val2 are the corresponding values.

See Querying data for an explanation of filter syntax.

Example

Request without filter:

Request URL: GET http://localhost:3000/api/locations

Request with a filter to limit response to two records:

Request URL: GET http://localhost:3000/api/locations?filter[limit]=2

Response status code: 200

Response body:

[
 {
 "id": "87",
 "street": "7153 East Thomas Road",
 "city": "Scottsdale",
 "zipcode": 85251,
 "name": "Phoenix Equipment Rentals"
 },
 {
 "id": "88",
 "street": "390 Lang Road",
 "city": "Burlingame",
 "zipcode": 94010,
 "name": "Bay Area Firearms"
 }
]

Find first instance

Find first instance of the model matched by filter from the data source.

GET /modelName/findOne?filter=[filterType1]=val1&filter[filterType2]=val2...

Arguments

Query parameters:

• filterType1, filterType2, and so on, are the filter types.
• val1, val2 are the corresponding values.

See Querying data for an explanation of filter syntax.

Example

Request URL: GET http://localhost:3000/api/locations/findOne?filter[where][city]=Scottsdale

Response status code: 200

Response body:

{
 "id": "87",
 "street": "7153 East Thomas Road",
 "city": "Scottsdale",
 "zipcode": 85251,
 "name": "Phoenix Equipment Rentals"
}

Delete model instance

Delete a model instance by ID from the data source

DELETE /modelName/modelID

Arguments

• modelID - model instance ID

Example

Request URL: DELETE http://localhost:3000/api/locations/88

Response status code: 204

Delete all matching instances

Delete model instanced from the data source that match the specified where clause.

DELETE /modelName?filter=[filterType1]=val1&filter[filterType2]=val2...

Arguments

Query parameters:

• filterType1, filterType2, and so on, are the filter types.
• val1, val2 are the corresponding values.

See Querying data for an explanation of filter syntax.

Example

Request URL: DELETE http://localhost:3000/api/locations?[where][city]=Dallas

Response status code: 200

Get instance count

Count instances of the model from the data source matched by where clause.

GET /modelName/count?where[property]=value

Arguments

• where - criteria to match model instances. See Where filter for more information.

Example

Count without "where" filter

Request URL: GET http://localhost:3000/api/locations/count

Count with a "where" filter

Request URL: GET http://localhost:3000/api/locations/count?where[city]=Burlingame

Response status code: 200

Response body:

{count: 6}

Update model instance attributes

Update attributes of a model instance and persist into the data source.

PUT /model/</i>modelID</i>

Arguments

• data - An object containing property name/value pairs
• model - The model name
• modelID - The model instance ID

Example

Request URL: PUT http://localhost:3000/api/locations/88

Request body:

{"name": "L2"}

Response status code: 200

Response body:

{
 "id": "88",
 "street": "390 Lang Road",
 "city": "Burlingame",
 "zipcode": 94010,
 "name": "L2"
}

Update matching model instances

Update attributes of matching model instances and persist into the data source.

POST /modelName/update?where[property]=value...

Arguments

• data - An object containing property name/value pairs.
• where - The where object to select matching instances. See Where filter for more information.

Example

Request URL: POST http://localhost:3000/api/locations/update?where[city]=Burlingame

Request body:

{"city": "San Jose"}

Response status code: 200

Create Change Stream

Create a new change stream.

POST /modelName/change-stream?format=event-stream

Arguments

• Form data - Model instance data. JSON representing a single model instance or an array of model instances.

Example

Request URL: POST http://localhost:3000/api/locations/

Request body:

{"city": "San Jose"}

Get Change Stream

Fetch a change stream.

GET /mode/change-stream?format=event-stream