npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

loopback-connector-rest-hdr

v3.4.5

Published

Loopback REST Connector being able to response with headers

Downloads

12

Readme

loopback-connector-rest-hdr

Overview

The LoopBack REST connector enables applications to interact with other (third party) REST APIs using a template-driven approach. It supports two different styles of API invocations:

Installation

In your application root directory, enter:

$ npm install loopback-connector-rest-hdr --save

This will install the module from npm and add it as a dependency to the application's package.json file.

Creating a REST data source

Use the data source generator to add a REST data source to your application.

For LoopBack 2.x:

$ apic create --type datasource

For LoopBack 2.x or 3.0:

$ lb datasource

When prompted, scroll down in the list of connectors and choose REST services (supported by StrongLoop). This adds an entry to datasources.json, for example:

...
  "myRESTdatasource": {
    "name": "myRESTdatasource",
    "connector": "rest-hdr"
  }
...

Configuring a REST data source

Configure the REST connector by editing datasources.json manually (for example using the Google Maps API):

/server/datasources.json

...
"geoRest": {
  "connector": "rest-hdr",
  "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",
      "responseHeaders": true
    },
    "functions": {
      "geocode": ["street", "city", "zipcode"]
    }
  }]
}
...

The operations property is an array of objects, each of which can have these properties:

The example above creates a function geocode(street, city, zipcode) whose first argument is street, second is city, and third is zipcode.  LoopBack application code can call the function anywhere; for example, in a boot script, via middleware, or within a model's JavaScript file if attached to the REST datasource. 

Configure options for request

The REST connector uses the request module as the HTTP client. You can configure the same options as for the request() function. See request(options, callback).

You can configure options options property at two levels:

  • Data source level (common to all operations)
  • Operation level (specific to the declaring operation)

The following example sets Accept and Content-Type to "application/json" for all requests. It also sets strictSSL to false so the connector allows self-signed SSL certificates.

/server/datasources.json

{
  "connector": "rest-hdr",
  "debug": false,
  "options": {
    "headers": {
      "accept": "application/json",
      "content-type": "application/json"
    },
    "strictSSL": false
  },
  "operations": [
    {
      "template": {
        "method": "GET",
        "url": "http://maps.googleapis.com/maps/api/geocode/{format=json}",
        "query": {
          "address": "{street},{city},{zipcode}",
          "sensor": "{sensor=false}"
        },
        "options": {
          "strictSSL": true,
          "useQuerystring": true
        },
        "responsePath": "$.results[0].geometry.location",
        "responseHeaders": true
      },
      "functions": {
        "geocode": ["street", "city", "zipcode"]
      }
    }
  ]
}

Resource operations

If the REST API supports create, read, update, and delete (CRUD) operations for resources, you can simply bind the model to a REST endpoint that follows REST conventions.

For example, the following methods would be 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

For example:

/server/boot/script.js

module.exports = function(app) {
  var ds = app.loopback.createDataSource({
    connector: require("loopback-connector-rest-hdr"),
    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);
  });
}

Setting the resource URL

You can set the remote URL when using create, read, update, or delete functionality by setting the resourceName property on a model definition. This allows for a local model name that is different from the remote resource name.

For example:

var config = {
  "name": "ServiceTransaction",
  "base": "PersistedModel",
  "resourceName": "transactions"
}

var ServiceTransaction = ds.createModel('ServiceTransaction', {}, config);

Now there will be a resource model named ServiceTransaction, but whose URLs call out to baseUrl - '/transactions'

Without setting resourceName the calls would have been made to baseUrl - '/ServiceTransaction'.

Defining a custom method using a template

The template object specifies the REST API invocation as a JSON template, with the following properties:

| Property | Description | Type | |----------|-------------|------| | method| HTTP method | String (one of "GET", "POST", "PUT", and so on). | | url| The URL of the request | String; template values allowed. | | headers| HTTP headers | Object | | query| Query strings | Object; template values allowed. | | responsePath| Optional JSONPath applied to the HTTP body. See https://github.com/s3u/JSONPath for syntax of JSON paths.| String | | responseHeaders| A flag to indicate whether or not response headers. (Since 3.4.5) | boolean |

The template variable syntax is:

{name=defaultValue:type}

To specify that the variable value is required, add the prefix ! or ^.

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",
    "responseHeaders": true
  }

The following table provides several examples:

To use custom methods, configure the REST connector with the operations property, which is an array of objects, each of which can have these properties:

  • template defines the API structure.
  • functions defines JavaScript methods that accept the specified list of parameter names.
var loopback = require("loopback");

var ds = loopback.createDataSource({
  connector: require("loopback-connector-rest-hdr"),
  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",
      "responseHeaders": true
    },
    functions: {
      "geocode": ["street", "city", "zipcode"]
    }
  }]
});

Now you can invoke the geocode API in Node.js as follows:

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

By default, the 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);

Parameter/variable mapping to HTTP (since 2.0.0)

NOTE: This feature is available with loopback-connector-rest-hdr version 2.0.0 and later.

By default, variables in the template are mapped to HTTP sources based on their root property.

You can further customize the source in the parameter array of the function mapping, for example:

{
  "template": {
    "method": "POST",
    "url": "http://localhost:3000/{p}",
    "headers": {
      "accept": "application/{format}"
    },
    "query": {
      "x": "{x}",
      "y": 2
    },
    "body": {
      "a": "{a:number}",
      "b": "{b=true}"
    }
  },
  "functions": {
    "myOp": [
      "p",
      "x",
      "a",
      {
        "name": "b",
        "source": "header"
      }
    ]
  }
}

For the template above, the variables will be mapped as follows:

  • p - path
  • x - query
  • a - body
  • b - header

Please note that path variables are appended to the path, for example, /myOp/:p.