Nuclear Pumpkin Mayhem

    @baiducloud/restclient
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.2 • Public • Published

    RestClient

    build Coverage Status

    Restful HTTP Client for broswer.

    Installation

    Using npm:

    $ npm install @baiducloud/restclient
    

    Example

    Basic use as a post method.

    import {Client} from '@baiducloud/restclient';
    
    const client = new Client();
    const params = {
        name: 1
    };
    const options = {
        headers: {
            'X-request-By': 'RestClient'
        }
    };
    client.post('/api/test', params, options).then(data => {
        ...
    });

    Use as a base Class to extended in ES6.

    import {Client} from '@baiducloud/restclient';
    
    export default new class extends Client {
        constructor() {
            const options = {
                headers: {
                    'X-request-By': 'RestClient'
                }
            };
            super(options);
        }
    
        getList(params) {
            this.get('/api/getList', params);
        }
    }

    Build your own plugins to handle request and response.

    import {Client, decorators} from '@baiducloud/restclient';
    
    const {use, retry} = decorators;
    
    const requestPlugin = region => (req, next) => {
        req.region = region || {};
        req.headers = Object.assign({}, req.headers, {'x-region': region});
    
        next();
    };
    
    const responsePlugin = () => (res, next) => {
        if (!res.data.success || res.data.success === 'false') {
            res.status = 500;
            res.data.error = 'Internal Server Error.';
        }
    
        next();
    };
    
    @use('request', requestPlugin())
    @use('response', responsePlugin())
    class TestClient extends Client {
    
        @retry()
        getList(params) {
            this.get('/api/getList', params);
        }
    }
    
    export default new TestClient();

    Options

    There are some options offer to config. You can init them in constructor or as an option when exec a restful method.

    {
        //  the request headers
        headers: {}
    
        //  if the request time out, it will be aborted
        timeout: 0
    
        //  a function to validate response status
        validateStatus: function(status) {
            return status >= 200 && status < 300;
        }
    
        // specifies what type of data the response contains
        responseType: null
    
        //  the config is a Boolean that indicates whether or not cross-site Access-Control requests
        //  should be made using credentials such as cookies, authorization headers or TLS client certificates
        withCredentials: false,
    
        //  a function to handle the download progress event
        onDownloadProgress: null
    
        //  a function to handle the upload progress event
        onUploadProgress: null
    
        /**
            next three options can alse be set in options,
            but it's not a good practice to do this instead of using restful methods.
        **/
    
        //  the request url
        url: *
    
        //  the request method
        method: *
    
        //  the request data
        data: *
    }

    Decorators

    RestClient expect the developer to use decorators to extend the client. And there also provide some decorators inside.

    • use - Use plugins for a class or a method
    • retry - Provide the retry function
    • timeout - Provide the timeout function

    Plugins

    Plugins execute in order.

    The plugin is the most important part of restclient. It makes it easy to extends our api requester, particularly in complicated WebApps. And it's coupling with business is very low, therefore easy to be changed and replaced.

    Example we have used several customized plugins in BaiduCloud.

    • headers plugin to handle different headers.
    • crsf plugin to handle crsftoken.
    • sdk plugin to handle sdk requests.
    • mfa plugin to handle Multi-factor authentication.
    • response plugin to handle common response.
    • notification plugin to handle common error windows.
    • monitor plugin to collect requests infos.

    RestClient has two plugin queues, respectively are the request queue as req property and the response queue as res property.

    The default request plugin:

    export default () => (req, next) => {
        //  set default request headers
        req.headers = req.headers || {};
        req.headers['Content-Type'] = 'application/x-www-form-urlencoded;charset=utf-8';
    
        if (utils.isObject(req.data)) {
            req.headers['Content-Type'] = 'application/json;charset=utf-8';
            req.data = JSON.stringify(req.data);
        }
    
        //  set requester info
        req.headers['X-Request-By'] = 'RestClient';
    
        //  set csrftoken
        req.headers.csrftoken = new Date().getTime();
    
        //  to handle next plugin
        next();
    };

    The default response plugin:

    export default () => (res, next) => {
        if (typeof res.data === 'string') {
            try {
                res.data = JSON.parse(res.data);
            } catch (e) { /* Ignore */ }
        }
    
        next();
    };

    How to build a plugin?

    A plugin is just like a nodejs middleware, it receive two params (the first is req/res and the second is next).

    You can handle the request or the response in your plugin, but remember to exec next function or the next plugin will not be executed.

    In the end, you need to use your plugin by client.req|res.use() method.

    import {Client} from '@baiducloud/restclient';
    
    const client = new Client();
    
    client.requestPlugins.push((req, next) => {
        //  handle request
    
        //  remember next()
        next();
    });
    
    client.responsePlugins.push((res, next) => {
        //  handle response
    
        //  remember next()
        next();
    });

    Plugin apis

    Plugin offers some apis for handle plugins more convenient.

    • plugin.use(fn) // to push a plugin in queue
    • plugin.handle(options) // start handle options in plugins one by one
    • plugin.abort(index) // abort a plugin in queue by index

    Methods

    RestClient offers four Restful methods as getputpostdelete. And the api returns a Promise.

    client.get|post|put|patch|head|delete(url, data, options);

    It also supports to add method by using request method in prototype.

    import Client from '@baiducloud/restclient';
    
    class extends Client {
        patch(url, data, options) {
            const config = {
                url,
                data
            };
    
            return this.request(Object.assign({}, config, options));
        }
    }

    License

    MIT

    Keywords

    none

    Install

    npm i @baiducloud/restclient

    DownloadsWeekly Downloads

    2

    Version

    1.0.2

    License

    MIT

    Unpacked Size

    151 kB

    Total Files

    15

    Last publish

    Collaborators

    • lurunze
    • bce-cfc-dev
    • xiaojiaolv
    • yangwei9012
    • qianchuan