@bowtie/api

JavaScript utilities and helpers

• Installation
• Documentation
• Basic Usage
  • GET Example
  • POST Example
  • PUT Example
  • DELETE Example
• Base URL Config
• Authorization
  • Basic Auth
  • Bearer Token
  • Custom Auth
• Ignore Security
• Enable Debug Logs

Installation

npm install --save @bowtie/api

Documentation

Documentation

Basic Usage

// Require @bowtie/api class definition
const Api = require('@bowtie/api')

// Create api instance
const api = new Api({
  root: 'api.example.com' // Will default to https:// if no protocol is provided here
})

GET Example

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

POST Example

// REST POST /todos - Create new todo
api.post('todos', { name: 'new todo' })
  .then(resp => {
    // resp = response from POST https://api.example.com/todos
  })
  .catch(err => {
    // Something went wrong
  })

PUT Example

// REST PUT /todos/1 - Update todo with id=1
api.put('todos/1', { name: 'changed name' })
  .then(resp => {
    // resp = response from PUT https://api.example.com/todos/1
  })
  .catch(err => {
    // Something went wrong
  })

DELETE Example

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

Base URL Config

// Create api instance
const api = new Api({
  root: 'api.example.com', // Set beginning of the baseUrl to https://api.example.com
  stage: 'test',           // Append "/test" to baseUrl (i.e. https://api.example.com/test)
  prefix: 'api',           // Append "/api" to baseUrl  (i.e. https://api.example.com/test/api)
  version: 'v1'            // Append "/v1" to baseUrl   (i.e. https://api.example.com/test/api/v1)
})

// baseUrl is constructed as follows: (only api.root is required, any combination of stage/prefix/version is allowed)
baseUrl = `${api.root}/${api.stage}/${api.prefix}/${api.version}`;

Authorization

Basic Auth

// Create api instance
const api = new Api({
  root: 'api.example.com', // Will default to https:// if no protocol is provided here
  authorization: 'Basic'   // Specify Basic authorization type for this api
})

// Authorize api for basic auth with username & password
api.authorize({
  username: 'user',
  password: 'pass'
})

Bearer Token

// Create api instance
const api = new Api({
  root: 'api.example.com', // Will default to https:// if no protocol is provided here
  authorization: 'Bearer'  // Specify Bearer authorization type for this api
})

// Authorize with static token value
api.authorize({
  token: 'abc123'
})

// Authorize with dynamic token function
api.authorize({
  token: () => localStorage.getItem('access_token')
})

Custom Auth

// Create api instance
const api = new Api({
  root: 'api.example.com', // Will default to https:// if no protocol is provided here
  authorization: 'Custom'  // Specify Custom authorization type for this api
})

// Authorize with static headers
api.authorize({
  headers: {
    'token': 'abc123'
  },
  validate: () => {
    // Function to validate the custom auth, returns true/false
    return true
  }
})

// Authorize with dynamic headers
api.authorize({
  token: () => ({
    'token': localStorage.getItem('access_token'),
    'uid': localStorage.getItem('uid')
  }),
  validate: () => {
    // Function to validate the custom auth, returns true/false
    return true
  }
})

Example using the j-toker package with headers from devise_token_auth

const Auth = require('j-toker')

// Configure j-toker apiUrl to match api.baseUrl()
Auth.configure({
  apiUrl: api.baseUrl()
})

// Authorize with custom headers that retrieve authHeaders from j-toker "Auth" instance
api.authorize({
  headers: () => Auth.retrieveData('authHeaders'),
  validate: () => Auth.user.signedIn
})

Ignore security

// Create api instance
const api = new Api({
  root: 'http://localhost:3000', // Use a local development API over HTTP (not secure HTTPS)
  secureOnly: false              // Disable secure HTTPS requirement
})

Enable Debug logs

// Create api instance
const api = new Api({
  root: 'api.example.com', // Will default to https:// if no protocol is provided here
  verbose: true            // Set verbose=true to enable debug log output
})