interfacer v0.1.4

Interfacer.js

Interfacer.js is a convenient module for working with RESTful API from Client.

Key Features:

• Unopinionated about frameworks you use
• Highly customizable
• Memoization by default
• Simple error handling, that fits your system
• Customizable query construction
• Optional normalizr integration

How to install

yarn add interfacer

or

npm install interfacer --save

Configuration & Interface Creation

The most advanced feature, Interfacer.js provides, are 3 levels of configuration (Application level, Single Interface/Collection level, Request level). In every configuration level you can define things like defaultError, baseUrl, custom querybuilder and more. Each level of configuration overrides previous (more global ones), so you can change everything, mid-action, on the fly if you need to.

Don't panic as you'll see all them references to Redux like dispatch. Their's purpose is purely illustrative. you can provide any kind of function, that handles your data.

Application Level

import interfacer from 'interfacer';

const globalConfig = {
  baseUrl: 'http://localhost:8080/api',
  defaultError: new Error('Something broke'),
  errorHandler: ({error, message}) => dispatch({ type: 'API_ERROR', payload: message })
}

const createInterface = interfacer(globalConfig);

All of above settings will apply to every interface instance you create with this createInterface function, unless overwritten by later configurations in more "local" level.

Interface level

Also can be perceived as "collection level". In for example Redux I'd recommend to have one interface for each collection reducer. From server perspective, there is one interface per resource.

const localConfig = {
  defaultError: new Error('Articles API error'),
  querybuilder: myCustomQueryBuilder,
  headers: { 'Content-Type': 'text/html' }
  request: { mode: 'cors' },
  flatMethod: parseXMLFunction,
  errorHandler: err => dispatch({ type: 'API_ERROR', payload: err })
}

const articleInterface = createInterface('/articles', localConfig);

On Interface level you always specify resource. That is route that will be appended to baseUrl in all requests you do, with this interface. resource string is always passed to createInterface function as a first paramtere. Obviously you can (and will) have many different Interfaces.

Request level

This final and most local level references to a certain requests you make with your interface. Each call returns a promise with your flattened (see flatMethod) response.

const requestOptions = {
  query: { fields: ['title', 'author']},
  defaultError: new Error('Articles Collection failed to fetch')
};

articleInterface
	.getCollection(requestOptions)
  .then(data =>
  	dispatch({ type: 'RECIEVE_ARTICLES', payload: data })
  );

Overview

Once you've created your interface network and configured it, it's time for you to do some fetching. Every interface has following methods get, getCollection, update, create and remove. Once called, each function returns a Promise, that contains response of the fetch as a frist parameter. Here is their API annotation.

get

(id :string | number, requestConfig? :Object) => Promise<Response>

getCollection

(requestConfig? :Object) => Promise<Response>

create

(body :Object, requestConfig? :Object) => Promise<Response>

remove

(id :ID, requestConfig? :Object) => Promise<Response>

update

(id :string, body :Object, requestConfig? :Object) => Promise<Response>

API Reference

Config Properties

Note on normalization:

Normalization of the response will take place after flatMethod is applied. Also schema property can be only configured in either Interface level or Request level config, as it doesn't really make sense to use one schema for all requests.

URL Queries

You can pass your own querybuilder into any config, but you can also use default one. Annotation of querybuilder looks like this

 querybuilder(query :Object) => string

Default querybuilder builds queries like this...

querybuilder({
  filters: 'over18',
  fields: ['title', 'years old']
});
// -> 'filters=over18&fields=title&fields=years%20old'