redux-rest-middleware

Redux Middleware for seamless REST communications.

Installation

Install using either npm or yarn:

npm install @rednetio/redux-rest-middleware

yarn add @rednetio/redux-rest-middleware

API

Usage

Enhance your Redux store with the middleware

import { applyMiddleware, createStore } from 'redux';
import restMiddleware from '@rednetio/redux-rest-middleware';

const storeEnhancer = applyMiddleware(
  restMiddleware({
    base: 'http://localhost:3000',
    authorization: getState => `Bearer ${getState().session.jwt}`,
  }),
);

const store = createStore(reducer, initialState, storeEnhancer);

Add meta properties to your action

See the Meta properties section for more information.

const listTodos = () => ({
  type: 'LIST_TODOS',
  meta: {
    rest: '/todos',
  },
});

Handle actions in your reducer

const reducer = (state = initialState, { type, payload }) => {
  switch (type) {
    case 'LIST_TODOS_REQUEST':
      return {
        ...state,
        loading: true,
        error: null,
      };

    case 'LIST_TODOS_SUCCESS':
      return {
        ...state,
        todos: payload,
      };

    case 'LIST_TODOS_FAILURE':
      return {
        ...state,
        error: payload,
      };

    case 'LIST_TODOS_FINALLY':
      return {
        ...state,
        loading: false,
      };
  }
}

Middleware options

The restMiddleware function takes an optional options object that may contain any of the following keys:

authorization

You must provide an authorization function if you wish to use the authenticated: true (default) meta property. See the Authentication section for more information.

base

Useful if you only ever hit one server: the base will be concatened with your meta rest property to form the full endpoint. Defaults to ''.

fetch

If you need to support older browsers or server-side rendering you’ll want to provide a fetch polyfill. Defaults to the global fetch which is available in modern browsers.

encode

Either 'json', 'form' or a custom encoding function that takes the payload object and returns an object with stringified data and a type property for the Content-Type header. Defaults to 'json', which for reference is implemented like this:

function encode(payload) {
  return {
    type: 'application/json',
    data: JSON.stringify(payload),
  };
}

decode

Either 'json', 'form' or a custom decoding function that takes the data string and a type (Content-Type header) and returns an object. Defaults to 'json', which for reference is implemented like this:

function decode(data, type) {
  if (type.indexOf('application/json') !== 0) {
    throw new Error('Unsupported Content-Type');
  }

  return JSON.parse(data);
}

suffixes

Provide an array if you want to have other action types. Defaults to ['_REQUEST', '_SUCCESS', '_FAILURE', '_FINALLY'].

Meta properties

authenticated

Wether to set an Authorization request header or not. See the Authentication section for more information. Defaults to true.

method

HTTP method. Defaults to GET.

rest

The REST endpoint you want to hit. Required.

body

Payload to send as the request body.

Authentication

All requests are authenticated by default, which means the authorization function will be called each time to provide an Authorization request header.

You set the authorization function in the middleware options. It takes a getState function as an argument, which returns the current state. You can return:

a string, which will be the Authorization header’s value,
a { header: value } object to specify multiple or different headers (e.g. { 'X-Token': 'value' }),
alternatively, an array of [header, value] tuples to specify multiple or different headers (e.g. [['X-Token', 'value']]),
false (the default) to disable authentication entirely. Note that this will throw an error whenever authenticated: true is passed in a meta.

Usage with redux-actions

redux-rest-middleware interfaces nicely with redux-actions.

See the redux-actions example for details.