Api

Api

Api class to handle all interactions with backend

Constructor

new Api(settings)

Constructor for an Api object

Source:
Parameters:
Name Type Description
settings ApiSettings

Settings to create api instance

Methods

_debug(…args)

Console log all arguments if verbose setting is true

Source:
Parameters:
Name Type Attributes Description
args * <repeatable>

All args passed to console.log

authorize(args)

Authorize this API. If token is provided, it will be used for authorization. If username/password are provided, settings.authorization must be set to 'Basic', and a token will be generated using Api#base64encode with input: ${username}:${password}

Source:
Parameters:
Name Type Description
args object
Name Type Attributes Description
token string | function <optional>

A token string, or a function to obtain a token value
username string | function <optional>

A username string, or a function to obtain a username value
password string | function <optional>

A password string, or a function to obtain a password value
headers object | function <optional>

Custom authorization headers object, or a function to obtain them
validate function <optional>

Custom authorization validation function
Throws:
  • Arguments MUST provide headers, token OR username & password
Type
Error

base64decode(b64, formatopt) → {string}

Decode given base64 string

Source:
Parameters:
Name Type Attributes Default Description
b64 string

Base64 string to be decoded
format string <optional>
 'utf8'

Target format for decoded string
Returns:
Type:
string
  • Returns base64 decoded string
Example

Example usage of base64decode.

api.base64encode('hello world'); // returns 'aGVsbG8gd29ybGQ='

base64encode(str) → {string}

Encode given string as base64

Source:
Parameters:
Name Type Description
str string

Input string to be encoded
Returns:
Type:
string
  • Returns base64 encoded string
Example

Example usage of base64encode.

api.base64encode('aGVsbG8gd29ybGQ='); // returns 'hello world'

baseUrl() → {string}

Construct the base URL for this API (using other member variables)

Source:
Returns:
Type:
string
  • Returns the constructed BaseUrl (root + stage + prefix + version)

buildUrl(path) → {string}

Build a request URL for a specific path

Source:
Parameters:
Name Type Description
path string

Build full request url for path
Returns:
Type:
string
  • Fully constructed request url

(async) callRoute(args) → {Promise.<object>}

Generic request execution method. For a GET request, only the "path" parameter is required

Source:
Parameters:
Name Type Description
args object

Arguments to call api route

Name Type Attributes Description
path string

Relative api path to fetch
options FetchOptions <optional>

Additional fetch options (will be assigned on top of defaults)
Returns:
Type:
Promise.<object>
  • Returns promise with response data

(async) delete(path, optionsopt) → {Promise.<object>}

Query API route for path using the DELETE method with a body

Source:
Parameters:
Name Type Attributes Description
path string

Request path
options object <optional>

Additional fetch options
Returns:
Type:
Promise.<object>
  • Returns promise with response data
Example

Example usage of delete.

var api = new Api({ root: 'api.example.com' })

api.delete('todos/1')
  .then(resp => {
    // resp = response from DELETE https://api.example.com/todos/1
  })
  .catch(err => {
    // Something went wrong
  })

(async) get(optionsopt) → {Promise.<object>}

Helper for simple GET requests (only need to call "api.get('something')")

Source:
Parameters:
Name Type Attributes Description
options object <optional>

Additional fetch options
Returns:
Type:
Promise.<object>
  • Returns promise with response data
Example

Example usage of get.

var api = new Api({ root: 'api.example.com' })

api.get('todos')
  .then(resp => {
    // resp = response from GET https://api.example.com/todos
  })
  .catch(err => {
    // Something went wrong
  })

handleEvents(response)

Process event emitters for response

Source:
Parameters:
Name Type Description
response object

Fetch response to trigger events

handleMiddlewares(response)

Process middleware chain

Source:
Parameters:
Name Type Description
response object

Fetch response to be passed through middleware chain

hasValidToken() → {boolean}

Check if this API instance has a valid token

Source:
Returns:
Type:
boolean
  • Whether or not this API instance has a valid token

Query API route for path using the HEAD method (no response body)

Source:
Parameters:
Name Type Attributes Description
path string

Request path
options object <optional>

Additional fetch options
Returns:
Type:
Promise.<object>
  • Returns promise with response data
Example

Example usage of head.

var api = new Api({ root: 'api.example.com' })

api.head('todos', payload)
  .then(resp => {
    // response from HEAD https://api.example.com/todos (no response body)

    // resp = {
    //   url: 'https://api.example.com/todos',
    //   status: 200,
    //   statusText: 'OK',
    //   headers: { ... }
    // }
  })
  .catch(err => {
    // Something went wrong
  })

init()

Initialize API instance

Source:
Throws:

Unable to load fetch library via NodeJS or window.fetch

Type
Error

isAuthorized() → {boolean}

Check if this API instance is authorized

Source:
Returns:
Type:
boolean
  • If this API instance has settings.authorization set and a valid token

(async) patch(path, bodyopt, optionsopt) → {Promise.<object>}

Query API route for path using the PATCH method with a body

Source:
Parameters:
Name Type Attributes Description
path string

Request path
body object <optional>

Request payload
options object <optional>

Additional fetch options
Returns:
Type:
Promise.<object>
  • Returns promise with response data
Example

Example usage of patch.

var api = new Api({ root: 'api.example.com' })

var payload = {
  todo: {
    name: 'new name (patched)'
  }
}

api.patch('todos/1', payload)
  .then(resp => {
    // resp = response from PATCH https://api.example.com/todos/1
  })
  .catch(err => {
    // Something went wrong
  })

(async) post(path, bodyopt, optionsopt) → {Promise.<object>}

Query API route for path using the POST method with a body

Source:
Parameters:
Name Type Attributes Description
path string

Request path
body object <optional>

Request payload
options object <optional>

Additional fetch options
Returns:
Type:
Promise.<object>
  • Returns promise with response data
Example

Example usage of post.

var api = new Api({ root: 'api.example.com' })

var payload = {
  todo: {
    name: 'foobar'
  }
}

api.post('todos', payload)
  .then(resp => {
    // resp = response from POST https://api.example.com/todos
  })
  .catch(err => {
    // Something went wrong
  })

(async) put(path, bodyopt, optionsopt) → {Promise.<object>}

Query API route for path using the PUT method with a body

Source:
Parameters:
Name Type Attributes Description
path string

Request path
body object <optional>

Request payload
options object <optional>

Additional fetch options
Returns:
Type:
Promise.<object>
  • Returns promise with response data
Example

Example usage of put.

var api = new Api({ root: 'api.example.com' })

var payload = {
  todo: {
    name: 'new name'
  }
}

api.put('todos/1', payload)
  .then(resp => {
    // resp = response from PUT https://api.example.com/todos/1
  })
  .catch(err => {
    // Something went wrong
  })

sanitize()

Sanitize all API variables for this API instance

Source:
Throws:

API root must be HTTPS if secureOnly is true in the ApiSettings

Type
Error

use(fn)

Register middleware

Source:
Parameters:
Name Type Description
fn function

Middleware function (must resolve with response)

validate()

Validate this API instance

Source:
Throws:
  • If required schema is invalid
Type
Error

varOrFn(ref, …args) → {*}

If ref is a function, execute with optional params. Otherwise, return value of ref

Source:
Parameters:
Name Type Attributes Description
ref *
args * <repeatable>
Returns:
Type:
*
  • Return value of ref(...args) or ref