backendless-request

    0.1.1 • Public • Published

    Backendless Request

    npm version

    Simple Node.js and Browser REST client

    backendless.js => ~ 28 KB
    backendless.min.js => ~ 11 KB
    

    How to use

    Install

    for installing just execute the following command:

    npm i backendless-request -S
    

    Require it as a module

    import BackendlessRequest from 'backendless-request';
     
    //or
     
    const BackendlessRequest = require('backendless-request');

    Include it as a single file

    Inside the installed package you can find a dist directory, where are two js files backendless-request.js and backendless-request.min.js

    -|
     - dist
        |-backendless.js
        |-backendless.min.js
     
    

    Get one of the js files into your project

    <script src="/path-to-backandless-request-package/dist/backendless-request.js"></script>

    you can use minimized file as well

    <script src="/path-to-backandless-request-package/dist/backendless-request.min.js"></script>

    After that you can use BackendlessRequest from the global scope

    BackendlessRequest.get('http://foo.bar/')

    Request Methods

    GET

    BackendlessRequest.get('http://foo.bar/')
      .then(result => console.log(result))
      .catch(error => console.error(error))

    POST

    BackendlessRequest.post('http://foo.bar/', { foo: 'bar', bool: true, num: 1 })
      .then(result => console.log(result))
      .catch(error => console.error(error))

    PUT

    BackendlessRequest.put('http://foo.bar/', { num: 123 })
      .then(result => console.log(result))
      .catch(error => console.error(error))

    DELETE

    BackendlessRequest.delete('http://foo.bar/foo')
      .then(result => console.log(result))
      .catch(error => console.error(error))

    PATCH

    BackendlessRequest.patch('http://foo.bar/foo', { bool: false })
      .then(result => console.log(result))
      .catch(error => console.error(error))

    Query Params

    You can set up request query through .query(query) method and the library automatically add the query into request url

    // RequestUrl: http://foo.bar/some-path?str=some-string&num=123&bool=true&arr=1&arr=2&arr=3&arr=4
    BackendlessRequest.get('http://foo.bar/some-path') 
      .query({ str: 'some-string', num: 123, bool: true, arr: [1, 2, 3, 4] })
      .then(result => console.log(result))
      .catch(error => console.error(error))

    Request Body

    You have an ability to send request body through .send(body) method, but if don't do that the method will be called with the second argument when you call then or catch method.

    BackendlessRequest.post('http://foo.bar/some-path') 
      .send({ str: 'some-string', num: 123, bool: true, arr: [1, 2, 3, 4] })
      .then(result => console.log(result))
      .catch(error => console.error(error))
    BackendlessRequest.post('http://foo.bar/some-path', { str: 'some-string', num: 123, bool: true, arr: [1, 2, 3, 4] }) 
      .then(result => console.log(result))
      .catch(error => console.error(error))

    Form

    For sending form you should use .form(form) method

    BackendlessRequest.post('http://foo.bar/')
      .form(form)
      .then(result => console.log(result))
      .catch(error => console.error(error))

    ContentType Header

    For set up Content-Type header manually you can use .type(contentTypeHeader) method or set it via .set('Content-Type', value) method. If you pass an object as request body the Content-Type header will be automatically specified as application/json

    BackendlessRequest.get('http://foo.bar/')
      .set('x-header-key', 'x-header-value')
      .set({ 'y-header-key': 'y-header-value', 'z-header-key': 'z-header-value' })
      .then(result => console.log(result))
      .catch(error => console.error(error))

    Request Events

    A request instance might fire events to notify about changing request state:

    for subscribing use method .on(<eventName>, callback)

    BackendlessRequest.post('http://foo.bar/some-path')
      .on('request', req => req.set('my-x-header-key', 'my-x-header-value')) 
      .on('response', result => console.log('result', result)) 
      .on('error', error => console.log('error', error))
      .on('done', (error, result) => console.log('done', { error, result })) 
      .send({ str: 'some-string', num: 123, bool: true, arr: [1, 2, 3, 4] })
      .then(result => console.log(result))
      .catch(error => console.error(error))
    • request - it will be fired before sending request to the server
    • response - it will be fired when request is successfully completed
    • error - it will be fired when request is failed
    • done - it will be fired when request is done, it's a shortcut for response and error

    Caching Requests

    The feature provides you to have some responses cached and reset the cache by the next requests.

    Cache Tags

    Cache tags help you to keep your cache up-to-date

    For example you have route to retrieve a list of Persons and you want to cache the result for the same requests, for it you need to specify a cache tag and set TTL via useCache method, after that when you do the request again the response will be retrieved from the cache store.

    // get list of persons
    BackendlessRequest.get('http://your-domain.com/persons')
      .cacheTags(['persons'])
      .useCache(30 * 1000) // cache time to live is 30 seconds, by default it's 15 seconds
      .then(result => console.log(result))
      .catch(error => console.error(error))

    You can use as many tags as you need

    // get list of persons
    BackendlessRequest.get('http://your-domain.com/persons')
      .cacheTags(['persons', 'friends', 'posts'])
      .useCache()
      .then(result => console.log(result))
      .catch(error => console.error(error))

    Reset Cache

    In many cases you want to reset the cache when do some requests which can change values on the server

    // create a new persons
    BackendlessRequest.post('http://your-domain.com/persons', { name: 'Bob' })
      .cacheTags(['persons'])
      .resetCache(true)
      .then(result => console.log(result))
      .catch(error => console.error(error))
    // create a new persons
    BackendlessRequest.delete('http://your-domain.com/persons/personId')
      .cacheTags(['persons'])
      .resetCache(true)
      .then(result => console.log(result))
      .catch(error => console.error(error))

    Own XMLHttpRequest

    You can use your own XMLHttpRequest, just replace it for BackendlessRequest namespace.

    See Example

     
    class MySupperXMLHttpRequest {
      
      open(){
        
      }
      
      ...
      
      send(){
        
      }
    }
     
    BackendlessRequest.XMLHttpRequest = MySupperXMLHttpRequest

    Logging

    If you want to logging all the requests just set true for verbose

    BackendlessRequest.verbose = true

    Keywords

    none

    Install

    npm i backendless-request

    DownloadsWeekly Downloads

    554

    Version

    0.1.1

    License

    MIT

    Unpacked Size

    227 kB

    Total Files

    22

    Last publish

    Collaborators

    • illya
    • stanislaw.grin
    • valodya
    • vengrov