Noncollinear Perpendicular Microcrystalline

    sync-rest-client

    1.0.3 • Public • Published

    Build Status

    sync-rest-client

    a very basic, synchronous, non-blocking, rest\http client with retries, timeouts, and graceful error handling


    Why ?

    originally I tried using the existing sync-request module - which works really great for most stuff! - but I ended up having some thread-blocking issues when running both a standard async module AND sync-request on the same thread.

    I created this module using deasync on top of request to solve that.


    Install

    npm install sync-rest-client
    

    Usage

    const syncClient = require('sync-rest-client');
     
    var response = syncClient.get('https://www.google.com');
     
    // that's it (;

    The Response Object

    for the most part, the response object is the same as the object that the original request module passes as the 2nd response argument to it's callbacks

    body if the response was a JSON-string, it will be parsed and body will be that JSON. otherwise, body will be a string

    statusCode if no errors were thrown, the http status code returned by the server. otherwise, statusCode will be undefined (this is one way to tell that there was an error - normally a timeout)

    retriesCount the number of retries that were used to complete the request. you can set this either globally for all requests using .setGlobalRetry(maxRetries) API, or by providing a retries key to the options object when sending a new request. default is 3 retries

    headers the response headers

    code if an error occurred while making the request, the error code will be populated onto this code property (such as ETIMEDOUT etc.)


    Errors

    things like 500 status-code (Internal Server Error) - or server timeouts (the request never reached the server) etc.

    these kind of errors are captured by the internal retry mechanism (configurable), and are populated on the response object on either the response.statusCode (when a status-code is available) or on response.code when the server didn't respond with a proper HTTP status code (timeout, unreachable etc..)

    all other HTTP status codes are reported through the response.statusCode property (404s etc) - together with the "healthy" status codes (200 OK \ 301 etc).

    when response.statusCode isn't available, the response will not have a body or headers (i.e. the server did not respond, so there's no HTTP data)


    Retries

    by default, each "failed" request will be retried 3 times before giving up. you can configure this either per request by providing the retries key to the options object when sending a request - or - if you want a global retry setting, you can use the .setGlobalRetry() API

    to disable the retry mechanism (so that the request will give up after the first attempt) simply set the retries count to 0 (zero);

    the response.retriesCount property shows how many retries were made for a given request


    API

    HTTP Methods

    syncClient.<verb>(url, [options])

    the basic syntax for sending a request is to use the corresponding verb method, passing in the url and an optional options object

    syncClient.get('https://www.google.com')
     
    // - or -
     
    syncClient.post('https://www.google.com', {payload:'hello world'})
     
    // etc..

    the following verbs are supported:

    • get
    • post
    • put
    • patch
    • del (not "delete")
    • head
    • options

    note: when using head, response.body will always be empty

    The options object

    timeout in seconds, the time to wait before giving up on a request default is 60 seconds

    retries the number of retries before giving up on a request default is 3 retries

    interval in seconds, the time to wait between each retry attempt

    headers an object of headers to add to the request. if global headers (see below) are configured, they will be mergerd and sent together with headers that you pass in

    payload the payload to be sent with the request. can either be a string or a json

    Global Module Settings

    you can use the following API to configure global settings that will apply for all requests

    note: options that are set using the options object take precedence over global configurations

    setGlobalRetry(numberOfRetries) set the number of retries to use before giving up on a request

    setGlobalInterval(seconds) set the number of seconds to wait before each retry. default is 1 second

    setGlobalTimeout(seconds) set the number of seconds to wait before giving up on a request

    addGlobalHeader(name, value) adds a global header that will be send with all requests. if at a later point the same header name is passed with the options.headers object for a specific request - the value of the header will be taken from there - ignoring the global header configuration

    removeGlobalHeader(name) removes a global header from being sent with all requests

    clearGlobalHeaders() an easy way to remove all global headers

    getGlobalHeaders() returns a copy of the global headers object (not the internal one that is actually used, that one is protected on purpose)

    note: no headers are added by default


    Test

    npm run test
    

    Related

    Install

    npm i sync-rest-client

    DownloadsWeekly Downloads

    427

    Version

    1.0.3

    License

    MIT

    Last publish

    Collaborators

    • ujc