@doxteam/service

service

External service call library based on middleware-tester. Mostly intended for JSON-based REST services.

Usage

To instantiate a service:

var Service = require("@doxteam/service");

var myService = new Service("http://www.exampleservice.com");
// Let's get a reponse from http://www.exampleservice.com/test
myService.get("/test").then(function(response) {
    console.log("Response", response.body);
});

You can also try to make a subclass and wrap your calls:

import Service = require("@doxteam/service");

class MyService extends Service {
    constructor() { super("http://www.exampleservice.com"); }

    test() {
        return this.get("/test").then(Service.extractBody);
    }
}

const myService = new MyService();
myService.test().then(responseBody => {
    console.log("Response", responseBody);s
});

Options

Requests can have additional options attached to them, either via parameter to each request or, if using your own subclass, overriding the getDefaultOpt function to apply the options to each request. The known options are:

• query - query string parameters.
• doNotParseResponse - if true, the service should not attempt to parse the incoming response as JSON.
• ignoreStatusCode - do not automatically throw an error if the status code is not one of the expected codes.
• rejectUnauthorized - if set to false, will not throw an error if an invalid certificate is used to sign a request.
• ca - specifies a certificate file.
• timeout (optional) - specifies a timeout in milliseconds after which the request is automatically aborted.

Return values

All request calls are asynchronous. The JSON-based values return a response stream that also acts as a promise-like object. The following methods are available on the response stream:

• then(succ, [err]) - works like a promise that resolves to the full response object, including headers and statusCode. Use body to get the parsed response body (if specified).
• expect(codes) - tells the request to regard the status codes specified by this method as success codes and throw an error if another code is received. Returns the same chainable object. Default values are 200 and 201. To allow all status codes, use the ignoreStatusCode request option.
• promise() - returns a real promise version of the object.

API

constructor(baseUrl, [auth])

Params

• baseUrl - the base URL of the service. Has to be a valid http or https URL. Adding a port number is also supported.
• auth (optional) - if any authorization parameters are needed, you can set them up with this object. The object must have a type string parameter and a credentials object parameter that depends on the type. type can have one of the following values:
  • "basic" - basic HTTP authentication. Needs username and password credentials.
  • "aws" - AWS authentication. Requires: secretAccessKey, region and accessKeyId.
  • "internal" - requires internalSecretHost.

getProtocol()

Returns the protocol part of the base URL for base classes.

getPath(path)

Returns the relative URL to a path for this service.

getFullPath(path)

Returns the full URL to a path for this service.

getDefaultOpt([headers], [additionalOptions])

Override in a subclass to provide your own default options and headers for each request. By default, it will inject the "X-Requested-With": "XMLHttpRequest" header in every request. Note that, even if not specified, requests with a body will have the "Content-Length" header set and JSON requests will have their "Content-Type" set to "application/json". Additional auth headers may be added if the auth parameter is specified during construction.

Must return the default options.

postForm(url, what, [headers])

POSTs a multipart/form to an URL. Returns the response stream.

post(url, what, [headers], [additionalOptions])

POSTs an object as JSON to an URL. Will hang if nothing is posted.

put(url, what, [headers], [additionalOptions])

PUTs an object as JSON to an URL. Will hang if nothing is posted.

patch(url, what, [headers], [additionalOptions])

Sends a PATCH request to an URL. Will hang if nothing is specified for a request body. By default, this request is expected to not have a body and the success code to be 204.

get(url, [qs], [headers], [additionalOptions])

GETs an URL, expecting a JSON response.

delete(url, [qs], [headers], [additionalOptions])

DELETEs a resource at an URL, expecting a JSON response.

options(url, [headers], [additionalOptions])

Makes an OPTIONS call to an URL.

postRaw(url, [headers], [what])

Makes a POST request without any JSON conversion and returns a stream. Mostly intended for piping your request body into the request stream: e.g.

var fs = require("fs");
var Service = require("@doxteam/service");
var myService = new Service("http://www.exampleservice.com");
fs.createReadStream("myfile").pipe(myService.postRaw("/testfile"));

getRaw(url, [qs])

Makes a GET request without any JSON conversion and returns a stream.

getRequestOptions(opt)

Gets the request options object for a given request.

extractBody(response)

Static convenience method that extracts the response body from the response object, mostly intended as a parameter for then, e.g.:

return this.get("/test").then(Service.extractBody).then(function(responseBody) {
    console.log("This is the body only", responseBody);
});