@novigi/api

Simple and lightweight Javascript Promise based API wrapper for Nodejs native https module 🍁

🐿 Features

• Chainable and immutable API
• Simple code to wrap HTTP calls with native and bulky https module
• Supports multipart/form-data submissions → with form method
• Invoking a backend API with customized headers

📦 Getting Started

1. Install the dependency

npm install @novigi/api

2. Import the library

const lib = require('@novigi/api');

📖 Documentation

api

This library contains methods to asynchronously invoke HTTP and HTTPS endpoints.

const api = require('@novigi/api')


const main = api("https://api.call")  // returns new `Api` object

try {
   let response = await main.header('Authorization', 'Bearer NksdfnIU')
                          .get()
                          .response()
} catch (err) {
   console.error(err)
}

// or

let response = await main.headers({'Authorization': 'Bearer NksdfnIU'})
                       .onStatusPattern('4[0-9]{2}', (response) => console.error(response))
                       .body({ 'posting': 'data'})
                       .post('/v2/blog')
                       .response()
                       .catch((err) => console.error(err))

// response => { headers: {...}, body: 'response' }

Chainable + immutable methods! ☝

• api
  • ~Api
    • .header ⇒ Api
    • .headers ⇒ Api
    • .httpOptions ⇒ Api
    • .response ⇒ Promise.<HttpResponse>
    • .json ⇒ Promise.<object>
    • .get ⇒ Api
    • .post ⇒ Api
    • .put ⇒ Api
    • .patch ⇒ Api
    • .delete ⇒ Api
    • .method ⇒ Api
    • .body ⇒ Api
    • .form ⇒ Api
    • .attach ⇒ Api
    • .onStatusPattern ⇒ Api
  • ~api(url, [options]) ⇒ Api
  • ~HttpResponse
  • ~statusCallback : function

api~Api

Kind: inner class of api

• ~Api
  • .header ⇒ Api
  • .headers ⇒ Api
  • .httpOptions ⇒ Api
  • .response ⇒ Promise.<HttpResponse>
  • .json ⇒ Promise.<object>
  • .get ⇒ Api
  • .post ⇒ Api
  • .put ⇒ Api
  • .patch ⇒ Api
  • .delete ⇒ Api
  • .method ⇒ Api
  • .body ⇒ Api
  • .form ⇒ Api
  • .attach ⇒ Api
  • .onStatusPattern ⇒ Api

api.header ⇒ Api

Adds a HTTP header to the request chain

Kind: instance property of Api
Returns: Api - new instance of Api object with same options

| Param | Type | Description | | --- | --- | --- | | key | string | key of the header | | value | string | value of the header |

Example

api('url').header('Authorization', 'Basic JHkasdfjh')

api.headers ⇒ Api

Adds HTTP header collection to the request chain

Kind: instance property of Api
Returns: Api - new instance of Api object with same options

| Param | Type | Description | | --- | --- | --- | | headers | object | HTTP headers collection |

Example

api('url').headers({ 'Authorization': 'Basic JHkasdfjh', 'X-Custom-header': true })

api.httpOptions ⇒ Api

Modifies native Nodejs HTTP request by overriding options parameter of http.request()

Kind: instance property of Api
Returns: Api - new instance of Api object with same options

| Param | Type | Description | | --- | --- | --- | | options | object | Options to be set in the native Nodejs HTTP request |

Example

api('url').httpOptions({ 'headers': { 'Authorization': 'Basic JHkasdfjh', 'X-Custom-header': true }})

api.response ⇒ Promise.<HttpResponse>

Invoking the backend endpoint

Kind: instance property of Api
Returns: Promise.<HttpResponse> - a Javascript promise object containing the response
Example

await api('url').get('/').response()   // { status: 200, headers: {...}, body: '<success>1</success>', response: {...} }

api.json ⇒ Promise.<object>

Invoking the backend endpoint and returning json parsed response body

Kind: instance property of Api
Returns: Promise.<object> - a Javascript promise object containing the response parsed to Javascript object
Example

await api('url').get('/').json()   // { response: 'Works!' }

api.get ⇒ Api

Creates an 'Api' obect for GET requests using resource path provided

Kind: instance property of Api
Returns: Api - new instance of Api object for a GET request

| Param | Type | Description | | --- | --- | --- | | [path] | string | resource path to be suffixed to base URL |

Example

api('url').get('/path')
api('url').get()

api.post ⇒ Api

Creates an 'Api' object for POST requests using resource path provided

Kind: instance property of Api
Returns: Api - new instance of Api object for a POST request

| Param | Type | Description | | --- | --- | --- | | [path] | string | resource path to be suffixed to base URL |

Example

api('url').post('/')

api.put ⇒ Api

Creates an 'Api' object for PUT requests using resource path provided

Kind: instance property of Api
Returns: Api - new instance of Api object for a PUT request

| Param | Type | Description | | --- | --- | --- | | [path] | string | resource path to be suffixed to base URL |

Example

api('url').put('/person/23')

api.patch ⇒ Api

Creates an 'Api' object for PATCH requests using resource path provided

Kind: instance property of Api
Returns: Api - new instance of Api object for a PATCH request

| Param | Type | Description | | --- | --- | --- | | [path] | string | resource path to be suffixed to base URL |

Example

api('url').patch('/person/23')

api.delete ⇒ Api

Creates an 'Api' object for DELETE requests using resource path provided

Kind: instance property of Api
Returns: Api - new instance of Api object for a DELETE request

| Param | Type | Description | | --- | --- | --- | | [path] | string | resource path to be suffixed to base URL |

Example

api('url').delete('/person/23')

api.method ⇒ Api

Creates an 'Api' object for given HTTP method with optional ontext path parameters

Kind: instance property of Api
Returns: Api - new instance of Api object for request

| Param | Type | Default | Description | | --- | --- | --- | --- | | [method] | string | "GET" | HTTP method (GET|POST|PUT|DELETE|PATCH|OPTIONS) | | [path] | string | | resource path to be suffixed to base URL |

Example

api('url').method('PATCH', '/item/21')
api('url').method('GET')

api.body ⇒ Api

Creates an 'Api' object for json body request

Kind: instance property of Api
Returns: Api - new instance of Api object for request

| Param | Type | Description | | --- | --- | --- | | data | object | Array | request payload as a Javascript object or array which will be converted to JSON inside the method |

Example

let payload = { field1: 'foo', field2: 'bar'}
api('url').body(payload)   // sets the request JSON encoded body
                           // { 'field1': 'foo', 'field2': 'bar'}

api.form ⇒ Api

Creates an 'Api' object for form post request with multipart/form-data content type

Kind: instance property of Api
Returns: Api - new instance of Api object for request

| Param | Type | Description | | --- | --- | --- | | data | object | a Javascript object which will be converted to form-data where object key being the form post element key and object value being the form post element value |

Example

let payload = { field1: 'foo', field2: 'bar'}
api('url').form(payload)    // sets the request body to have form-data
                            // field1  → foo
                            // field2  → bar

api.attach ⇒ Api

Creates an 'Api' object for uploading files with a post request with multipart/form-data content type

Kind: instance property of Api
Returns: Api - new instance of Api object for request

| Param | Type | Description | | --- | --- | --- | | fileBuffer | Buffer | file content which need to be upload | | filename | String | name that need to be given for the file |

Example

let fileBuffer = fs.readFileSync('./resources/test.pdf')  // Read the source file as a buffer
api('url').attach(fileBuffer, 'coco')  // sets the request body to upload the file
                            // file content  → fileBuffer
                            // file Name  → coco

api.onStatusPattern ⇒ Api

Registers a callback function for HTTP status code regex pattern. There can be multiple callback functions registered for a request chain.

Kind: instance property of Api
Returns: Api - new instance of Api object for a POST request

| Param | Type | Description | | --- | --- | --- | | statusRegex | string | regex pattern to match the response status code | | cb | statusCallback | callback function to be executed when matching status code is recieved |

Example

api('url').onStatusPattern('401', (response) => { console.error(response) })    // callback on status 401
api('url').onStatusPattern('20[0|1]', (response) => { console.log(response) })  // callback on status matching pattern 200 or 201

api~api(url, [options]) ⇒ Api

Create a API call chin builder instance

Kind: inner method of api
Returns: Api - new instance of Api object

| Param | Type | Default | Description | | --- | --- | --- | --- | | url | string | | base URL of the request builder | | [options] | object | | optional configurations for the request chain | | [options.baseUrl] | string | | base url of the request chain | | [options.method] | string | "GET" | HTTP method of the request chain | | [options.headers] | object | | HTTP headers of the request chain |

Example

api('url')           // new Api('url')
api('url', options)  // new Api('url', options)

api~HttpResponse

Kind: inner typedef of api
Properties

| Name | Type | Description | | --- | --- | --- | | status | number | HTTP response status code | | headers | object | response headers object | | body | string | response body as a raw string | | response | object | original response from the native HTTP request |

api~statusCallback : function

Callback function for the status matching

Kind: inner typedef of api

| Param | Type | Description | | --- | --- | --- | | res | object | response object called with successful callback invocation | | res.status | number | HTTP response status code | | res.headers | object | response headers object | | res.body | string | response body as a raw string | | res.response | string | original response from the native HTTP request |

This is an auto generated file. Please don't make changes manually