Redux API Middleman

A Redux middleware extracting the asynchronous behavior of sending API requests.

Usage:

Get Started:

• Create the middleware and put into your middleware chain:

import { createStore, applyMiddleware } from 'redux'
import createApiMiddleman from 'redux-api-middleman'

let apiMiddleware = createApiMiddleman({
  baseUrl: 'http://api.myapp.com',
})

const store = applyMiddleware(
  [ apiMiddleware ]
)(createStore)()

• Use it in your action creators:

// user action

import { CALL_API } from 'redux-api-middleman'

export const GETTING_MY_INFO = 'GETTING_MY_INFO'
export const GET_MY_INFO_SUCCESS = 'GET_MY_INFO_SUCCESS'
export const GET_MY_INFO_FAILED = 'GET_MY_INFO_FAILED'

export function getMyInfo() {
  return {
    [CALL_API]: {
      method: 'get',
      path: '/me',
      sendingType: GETTING_MY_INFO,
      successType: GET_CONTRACTS_SUCCESS,
      errorType: GET_MY_INFO_FAILED
    }
  }
}

• Handle it in your reducer:

// user reducer

import { GET_CONTRACTS_SUCCESS } from 'actions/users'

const defaultState = {}

export default function(state = defaultState, action) {
  switch(action.type) {
    case GET_CONTRACTS_SUCCESS:
      return action.response
    default:
      return state
  }
}

The code above would send a GET request to http://api.myapp.com/me, when success, it would dispatch an action:

{
  type: GET_CONTRACTS_SUCCESS,
  response: { the-camelized-response-body }
}

Features:

• Async to Sync: Abstract the async nature of sending API to make it easier to implement/test
• Universal Rendering Friendly
• Support chaining(successive) API calls
• Side Effect Friendly
• Replay request optionally when failed
• Tweek request/response format when needed

API Documentation:

Creation:

A middleware can be created like this:

import apiMiddleware from 'redux-api-middleman'

apiMiddleware({
  baseUrl: 'https://api.myapp.com',
  errorInterceptor: ({ err, proceedError, replay, getState })=> {
    // handle replay here
  },
  generateDefaultParams: ({ getState })=> {
    return {
      headers: { 'X-Requested-From': 'my-killer-app' },
    }
  },
  maxReplayTimes: 5
})

Options:

baseUrl: The base url of api calls(required)

errorInterceptor(optional):

When provided, this function would be invoked whenever an API call fails. The function signature looks like this:

({ err, proceedError, replay, getState })=> {

}

Where:

err is the error object returned by superagent, replay() can be used to replay the request with the same method/parameters, proceedError() can be used to proceed error to reducers

For example, to refresh access token when server responds 401:

({ err, proceedError, replay, getState })=> {
  if(err.status === 401) {
    refreshAccessToken().then((res)=> {
       // here you can pass additional headers if you want
       let headers = {
         'x-access-token': res.token,
       }
       replay({ headers })
     })
  } else {
    proceedError()
  }
}

The code above would do the token refreshing whenever err is 401, and proceed the original error otherwise.

generateDefaultParams(optional):

A function which takes ({ getState }) and returns an object like this:

{
  headers: { 'x-header-key': 'header-val' },
  query: { queryKey: 'query-val' },
  body: { bodyKey: 'body-val' }
}

On each request, the object returned by this function would be merged into the request's header, query, and body, respectively.

Usage In Action Creators:

In Action Creators, we can use the following code to send a single request:

import { CALL_API } from 'redux-api-middleman'

export const ON_REQUEST_SUCCESS = 'ON_REQUEST_SUCCESS'
export const ON_REQUEST_FAILED = 'ON_REQUEST_FAILED'
export const ON_SENDING_REQUEST = 'ON_SENDING_REQUEST'

export function getInfo({ username }) {
  return {
    extraKey: 'extra-val',

    [CALL_API]: {
      method: 'get',
      path: `/users/${username}/info`,
      successType: ON_REQUEST_SUCCESS,
      errorType: ON_REQUEST_FAILED,
      sendingType: ON_REQUEST_FAILED,
      afterSuccess: ({ getState, dispatch, response }) => {
        //...
      },
      afterError: ({ getState, error })=> {
        //...
      }
    }
  }
}

In short, just return an action object with CALL_API.

Options:

method(required):

Http verb to use, can be get, post, put or del

path(optional):

Request path to be concated with baseUrl

url:

Full url of request, will take precedence over path and will ignore baseUrl

camelizeResponse(optional):

Camelize response keys of the request. default to true

Transform { user_name: 'name' } to { userName: 'name' }

decamelizeRequest(optional):

Decamelize request payload keys. default to true

Transform { userName: 'name' } to { user_name: 'name' }

withCredentials(optional):

Enable Access-Control requests or not. default to true

sendingType(optional):

Action type to be dispatched immediately after sending the request

successType(required):

Action type to be dispatched after the API call success

errorType(optional):

Action type to be dispatched after the API call fails

afterSuccess(optional):

A callback function to be invoked after dispatching the action with type successType. ({ getState, dispatch, response }) would be passed into this callback function. This is a good place to handle request-related side effects such as route pushing.

afterError(optional):

A callback function to be invoked after dispatching the action with type errorType. ({ getState, error }) would be passed into this callback function.

Sending Chaining Requests:

To send chaining requests, just return an action with CHAIN_API-keyed object like this:

import { CALL_API, CHAIN_API } from 'redux-api-middleman'

export const ON_REQUEST_SUCCESS1 = 'ON_REQUEST_SUCCESS1'
export const ON_REQUEST_SUCCESS2 = 'ON_REQUEST_SUCCESS2'

export function getInfo({ username }) {
  return {
    [CHAIN_API]: [
      ()=> {
        return {
          extraKey: 'extra-val',
          [CALL_API]: {
            method: 'get',
            path: `/users/${username}/info`,
            successType: ON_REQUEST_SUCCESS1
          }
        }
      },
      (responseOfFirstReq)=> {
        return {
          [CALL_API]: {
            method: 'get',
            path: `/blogs/${responseOfFirstReq.blogId}`,
            successType: ON_REQUEST_SUCCESS2
          }
        }
      }
    ]
  }
}

In the code above, we send an API to /users/${username}/info to fetch user info containing a key blogId. After the first request is finished, we then send the second request with the blogId returned by server.

Usage In Reducers:

During the life cycle of an API call, several types of actions would be dispatched:

sendingType action:

After the request has been sent, an action of type sendingType would be dispatched immediately. The action would contain the key-val pairs other than CALL_API in the action object.

For example, if our action object looks like this:

{
  extraKey1: 'extra-val-1',
  extraKey2: 'extra-val-2',
  [CALL_API]: {
    ...
  }
}

then the sendingType action would be:

{
  type: sendingType,
  extraKey1: 'extra-val-1',
  extraKey2: 'extra-val-2'
}

successType action:

After the server responds successfully, an action of type successType would be dispatched. The action would contain:

• the key-val pairs other than CALL_API in the action object
• an extra response key, with its value be the server response

For example, if the server responds with a body like this:

{
  responseKey: 'response-val'
}

then the successType action would be:

{
  type: successType,
  extraKey1: 'extra-val-1',
  extraKey2: 'extra-val-2',
  response: {
    responseKey: 'response-val'
  }
}

errorType action:

After the server responds fails, an action of type errorType would be dispatched. The action would contain:

• the key-val pairs other than CALL_API in the action object
• an extra error key, with its value be the error object returned by axios

LICENCE:

MIT