HTTP API client

Primary designed for dc-api-core.

Basic usage

Import dc-api-client to your project

// Use Node.JS require
const API = require('dc-api-client');
// OR use import for ES6+/TS
import API from 'dc-api-client'

Make request to backend

const res = await API.Controller.action({
    // Any JSON-compatible types are supported.
    // You can also use Blob or File as the value.
});

• Controller - your controller name
• action - your action name in controller
• res - Response object

Response object

Name	Type	Note
success	Boolean	true if response code is 200
code	Number	HTTP response code
msg	any	If backend returned JSON, it will be parsed, otherwise contains raw response.

Example

Sending user data to register method in Auth controller.

const API = require('dc-api-client');
const res = await API.Auth.register({
    email: 'test@best.mail',
    password: '123123'
});
console.log(res);

Example console output:

{
    success: true,
    code: 200,
    msg: {
        status: 'user_registered',
        id: 42
    }
}

Sending request with query string

API.TestController.action(null, { query: 'works' });
// useKebab = false:    GET /TestController/action?query=works
// useKebab = true:     GET /test-controller/action?query=works

Settings

Settings stored in API.settings object.

Field	Type	Default	Note
secure	boolean	true	true - use HTTPS, instead of HTTP
base	string	location.hostname	Hostname with prefix path
dev	Function	Read-only	Enables or disables dev mode as setter, returns boolean as getter
reconnectAttempts	number	5	Count of WebSocket reconnection attempts, -1 is ∞
reconnectTimeout	number	2.5	WebSocket reconnection timeout is seconds
useKebab	boolean	false	true - automatically transform names to kebab-case
followRedirects	boolean	true	true - automatically redirect if "Location" header present

Settings example #1

const API = require('dc-api-client');

// Redundant, because HTTPS enabled by default
API.settings.secure = true;
API.settings.base = 'your-domain.com:8080/api';

Where your-domain.com is your domain or IP address.

Settings example #2

import API from 'dc-api-client';

API.settings.secure = false;
API.settings.base = `${location.hostname}:8080/api`;

Socket controller

WebSockets connection will be initialized when controller used for first time.

WS URI: ws[s]://<settings.base>/socket

API.Socket: {
    // Calling <event> method in Socket controller on back-end
    emit (event: String, ...arguments: any[]);

    // Sets trigger for <event> reply
    on (event: String, listener: (...arguments: any[]) => {});

    // Sets one time trigger for <event> reply
    once (event: String, listener: (...arguments: any[]) => {});

    // Removing trigger for <event>
    off (event: String, listener: (...arguments: any[]) => {});
};

Socket events

API.Socket.on('open', isReconnect => {
    if (isReconnect) console.log('Reconnected!');
    else console.log('Connected for first time');
});

API.Socket.on('reconnect', attempt => {
    // This event will be fired BEFORE reconnection
    if (API.settings.reconnectAttempts == -1) console.log(`[${attempt}/∞] Reconnecting...`);
    else console.log(`[${attempt}/${API.settings.reconnectAttempts}] Reconnecting...`);
});

API.Socket.on('close', (code, reason) => {
    // Reconnection never trigger this event,
    // i.e. on full connection lost
    console.log(`Connection was closed with code ${code}: ${reason || 'No reason provided'}`);
    // e - CloseEvent object (browser event)
});

API.Socket.on('<custom-event-name>', (a, b) => {
    // Handles event emitted from the server
    // For example, with dc-api-core you can use this line to emit your event
    //     this.emit('<custom-event-name>', 7, 5);
    // which will send packet below
    //     ["<custom-event-name>",7,5]
    // and will be handled here by dc-api-client
    console.log('New <custom-event-name> data!', a, b);
});

Advanced features

Multiple API connections

main.js:

import API from 'dc-api-client'
// Registering `ExampleAPI` in `API.instances`, this method also returns created instance
API.registerInstance('ExampleAPI', { base: 'api.example.com', secure: false });

other.js

import API from 'dc-api-client'
const { ExampleAPI } = API.instances;

// http://api.example.com/Controller/action
const res = await ExampleAPI.Controller.action();

// Works with WebSocket connection
// ws://api.example.com/socket
ExampleAPI.Socket.on('test', () => console.log('Test received'));
ExampleAPI.Socket.emit('send-me-test');

POST utility

Sends POST request in browser with form.

API.post(url: String, data: Object, newtab: Boolean = false);

Alternative request sending

API.send(controller: String, action: String, data: any, query: Object): Promise<Response>;

Known issues

dc-api-client doesn't work properly with Rollup

Inject NODE_ENV variable with process object manually or use rollup-plugin-inject-process-env.

Vanilla fallback

You can use pre-bundled version (browser.js ~4 kb) in browser without webpack, parcel, browserify or other bundlers.

Compatibility:

Internet Explorer	Edge	Firefox	Chrome	Safari	Opera
Not supported	12+	22+	49+	10+	36+