interfacer

Interfacer.js

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

Key Features:

• Unopinionated about frameworks you use
• Highly customizable
• Memoization
• Simple IO error handling, that fits your system
• Customizable query construction

How to install

yarn add interfacer

or

npm install interfacer --save

Configuration & Interface Creation

The most advanced feature Interfacer.js provides is 3 level of configuration (Application, Interface, Call). In configuration you can define things like defaultError, domain, protocol, and custom queryparser. 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 when you 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 = {
  protocol: 'https',
  domain: 'localhost',
  port: 8000,

  defaultError: new Error('Something broke'),
  throwError: err => dispatch({ type: 'API_ERROR', payload: err })
}

const createInterface = interfacer(globalConfig);

All of above settings will apply to every interface you create by 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.

const globalConfig = {
  defaultError: new Error('Articles API error'),
  constructFields: FieldsConstructor,
  headers: { 'Content-Type': 'text/html' }
  throwError: err => dispatch({ type: 'API_ERROR', payload: err })
}

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

On Interface level you always specify subdomain. That is route that will be appended to domain in all requests you do, with this interface. Obviously you can (and will) have many different Interfaces.

Call level

This final and most local level references to a certain calls you make with your interfac. .send() triggers the fetch and returns a promise.

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

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

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. Here is their API annotation. Every single one of them returns an Object containing method .send(). When this function is called, only then request is made. Finally .send() returns a promise, describing fulfillment status of the fetch.

get

args:

id :string, options :Object = {}, cb :Function = (data) => {}, shouldMemoize :boolean = true

getCollection

args:

options :Object = {}, cb :Function = (data) => {}, shouldMemoize :boolean = true

create

args:

body :Object, options? :Object, cb? :Function = (data) => {}

remove

args:

id :ID, options? :Object, cb? :Function = (data) => {}

update

args:

id :string, body :Object, options? :Object, cb? :Function = (data) => {}

API Reference

Config Properties

Property	Meaning	Type	Default
error	Error that gets sent to you via throwError fn once it occures	string or object	null
defaultError	If no error is found, defaultError gets sent to you	string or object	"unhandled Error"
throwError	Function that gets called if error occurs. As first argument your error will be passed	console.error
headers	Object containting headers your request should have	object	"Content-Type": "application/json"
query	Object that gets passed to queryparser fn	object	null
port	Number that gets appended to your domain	number or string or nothing	null
domain	baseUrl that your API runs on	string	localhost
protocol	Gets prepended to your domain	http or https	http
queryparser	Function that transform query object into a query string	function	queryparser

URL Queries

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

 queryparser(query :Object) => string

Default queryparser builds queries like this...

queryparser({
	filters: 'over18',
    fields: ['title', 'author']
});
// -> 'filters=over18&fields=title&fields=author'

Be careful though. This can be used only on very simple queries, that are safe. If you want full featured queryparser, I'd recommend use different package, or write your own. No sanitization provided.

Thank you

Thank you for using this package. If you have any issues, questions or suggestions, create an issue please, I'll be happy to answer it.