LoopBack REST Connector

LoopBack REST connector allows Node.js application to interact with HTTP REST APIs using a template driven approach. It supports two different styles of API invocations:

Resource CRUD

If the REST APIs supports CRUD operations for resources, such as users or orders, you can simply bind the model to a REST endpoint that follows REST conventions.

The following methods are mixed into your model class:

  • create: POST /users
  • findById: GET /users/:id
  • delete: DELETE /users/:id
  • update: PUT /users/:id
  • find: GET /users?limit=5&username=ray&order=email

Below is a simple example:

var ds = loopback.createDataSource({
    connector: require("loopback-connector-rest"),
    debug: false,
    baseURL: 'http://localhost:3000'
});

var User = ds.createModel('user', {
    name: String,
    bio: String,
    approved: Boolean,
    joinedAt: Date,
    age: Number
});

User.create(new User({name: 'Mary'}), function (err, user) {
    console.log(user);
});

User.find(function (err, user) {
    console.log(user);
});

User.findById(1, function (err, user) {
    console.log(err, user);
});

User.update(new User({id: 1, name: 'Raymond'}), function (err, user) {
    console.log(err, user);
});

Define a custom method using REST template

Imagine that you use browser or REST client to test drive a REST API, you will specify the following HTTP request properties:

  • method: HTTP method
  • url: The URL of the request
  • headers: HTTP headers
  • query: Query strings
  • responsePath: JSONPath applied to the HTTP body

LoopBack REST connector allows you to define the API invocation as a json template. For example,

    template: {
            "method": "GET",
            "url": "http://maps.googleapis.com/maps/api/geocode/{format=json}",
            "headers": {
                "accepts": "application/json",
                "content-type": "application/json"
            },
            "query": {
                "address": "{street},{city},{zipcode}",
                "sensor": "{sensor=false}"
            },
            "responsePath": "$.results[0].geometry.location"
        }

The template variable syntax is as follows:

{name=defaultValue:type}

The variable is required if the name has a prefix of ! or ^

For example:

'{x=100:number}'
'{x:number}'
'{x}'
'{x=100}ABC{y}123'
'{!x}'
'{x=100}ABC{^y}123'

To use custom methods, you can configure the REST connector with the operations property, which is an array of objects that contain template and functions. The template property defines the API structure while the functions property defines JavaScript methods that takes the list of parameter names.

var loopback = require("loopback");

var ds = loopback.createDataSource({
    connector: require("loopback-connector-rest"),
    debug: false,
    operations: [
    {
        template: {
            "method": "GET",
            "url": "http://maps.googleapis.com/maps/api/geocode/{format=json}",
            "headers": {
                "accepts": "application/json",
                "content-type": "application/json"
            },
            "query": {
                "address": "{street},{city},{zipcode}",
                "sensor": "{sensor=false}"
            },
            "responsePath": "$.results[0].geometry.location"
        },
        functions: {
           "geocode": ["street", "city", "zipcode"]
        }
    }
]});

Now you can invoke the geocode API as follows:

Model.geocode('107 S B St', 'San Mateo', '94401', processResponse);

By default, LoopBack REST connector also provides an 'invoke' method to call the REST API with an object of parameters, for example:

Model.invoke({street: '107 S B St', city: 'San Mateo', zipcode: '94401'}, processResponse);

LoopBack REST Connector API

exports.initialize(dataSource, [callback])

Export the initialize method to loopback-datasource-juggler

Arguments
Name Type Description
dataSource DataSource

The loopback data source instance
[callback] function

The callback function

RestConnector(baseURL, debug)

The RestConnector constructor

Arguments
Name Type Description
baseURL string

The base URL
debug boolean

The debug flag

restConnector.define(descr)

Hook for defining a model by the data source

Arguments
Name Type Description
descr object

The model description

restConnector.installPostProcessor(descr)

Install the post processor

Arguments
Name Type Description
descr object

The model description

restConnector.preProcess(data)

Pre-process the request data

Arguments
Name Type Description
data

The request data
Returns
Name Type Description
result [object Object]

restConnector.postProcess(model, data, many)

Post-process the response data

Arguments
Name Type Description
model string

The model name
data

The response data
many boolean

Is it an array

restConnector.getResource(model)

Get a REST resource client for the given model

Arguments
Name Type Description
model string

The model name
Returns
Name Type Description
result

restConnector.create(model, data, [callback])

Create an instance of the model with the given data

Arguments
Name Type Description
model string

The model name
data object

The model instance data
[callback] function

The callback function

restConnector.updateOrCreate(model, data, [callback])

Update or create an instance of the model

Arguments
Name Type Description
model string

The model name
data object

The model instance data
[callback] function

The callback function

restConnector.responseHandler(model, [callback])

A factory to build callback function for a response

Arguments
Name Type Description
model string

The model name
[callback] function

The callback function
Returns
Name Type Description
result function

restConnector.save(model, data, [callback])

Save an instance of a given model

Arguments
Name Type Description
model string

The model name
data object

The model instance data
[callback] function

The callback function

restConnector.exists(model, id, [callback])

Check the existence of a given model/id

Arguments
Name Type Description
model string

The model name
id

The id value
[callback] function

The callback function

restConnector.find(model, id, [callback])

Find an instance of a given model/id

Arguments
Name Type Description
model string

The model name
id

The id value
[callback] function

The callback function

restConnector.destroy(model, id, [callback])

Delete an instance for a given model/id

Arguments
Name Type Description
model string

The model name
id

The id value
[callback] function

The callback function

restConnector.all(model, filter, [callback])

Query all instances for a given model based on the filter

Arguments
Name Type Description
model string

The model name
filter object

The filter object
[callback] function

The callback function

restConnector.destroyAll(model, [callback])

Delete all instances for a given model

Arguments
Name Type Description
model string

The model name
[callback] function

The callback function

restConnector.count(model, [callback], where)

Count cannot not be supported efficiently.

Arguments
Name Type Description
model string

The model name
[callback] function

The callback function
where object

The where object

restConnector.updateAttributes(model, id, data, [callback])

Update attributes for a given model/id

Arguments
Name Type Description
model string

The model name
id

The id value
data object

The model instance data
[callback] function

The callback function

RestResource(modelCtor, baseUrl)

Build a REST resource client for CRUD operations

Arguments
Name Type Description
modelCtor function

The model constructor
baseUrl string

The base URL
Returns
Name Type Description
result RestResource

restResource.debug(enabled)

Enable/disable debug

Arguments
Name Type Description
enabled boolean

wrap(cb)

Wrap the callback so that it takes (err, result, response)

Arguments
Name Type Description
cb function

The callback function
Returns
Name Type Description
result

restResource.create(obj, [cb])

Map the create operation to HTTP POST /{model}

Arguments
Name Type Description
obj object

The HTTP body
[cb] function

The callback function

restResource.update(id, obj, [cb])

Map the update operation to POST /{model}/{id}

Arguments
Name Type Description
id

The id value
obj object

The HTTP body
[cb] function

The callback function

restResource.delete(id, [cb])

Map the delete operation to POST /{model}/{id}

Arguments
Name Type Description
id

The id value
[cb] function

The callback function

restResource.deleteAll(id, [cb])

Map the delete operation to POST /{model}

Arguments
Name Type Description
id

The id value
[cb] function

The callback function

restResource.find(id, [cb])

Map the find operation to GET /{model}/{id}

Arguments
Name Type Description
id

The id value
[cb] function

The callback function

restResource.all(q, [cb])

Map the all/query operation to GET /{model}

Arguments
Name Type Description
q object

query string
[cb] function

callback with (err, results)

module.exports