Functional Microservice Request Library

f is a Functional Microservice Request Library. It's a zero-dependency module that wraps HTTP(S) requests, intended for use with stateless, functional microservices. It's built to work out-of-the-box with services created using the stdlib microservice registry, but can be configured to use any gateway (and associated platform or infrastructure provider).

Installation

Node.js

For usage in an existing Node.js project, add it to your dependencies:

$ npm install f

And use it with the following line wherever you need it:

const f = require('f');

Web

Using Bower...

$ bower install poly/f

Or, simply copy web/f.js to wherever you keep your vendor scripts and include it as a script:

<script src="path/to/f.js"></script>

How do I use f?

f creates HTTP(S) requests following a custom specification that maps very closely to function invocation you're used to (as if it were running in a native environment). Let's say we have a microservice running on stdlib that calculates great-circle distances given two sets of coordinates using the Haversine formula.

The call to this service using f, might look like this;

// Calculate distance from Toronto to San Francisco
f('polybit/haversine')({
	from: [43.65, -79.38],
	to: [37.77, -122.42]
}, (err, result) => {

	console.log(result); // logs 3644329 (metres!)

});

Parameters: Arguments and Keyword Arguments

Usually when we make HTTP requests we think of querystring parameters, form-data, urlencoded variables and of course, json. With f, our goal is to standardize the way functional microservices are invoked (and deal with parameters) by referencing familiar concepts; function arguments and keyword arguments.

Arguments (args) are passed to functions as an array of basic JSON types (non-objects); number, boolean, string, null. Keyword arguments are allowed to be anything JSON-serializable (Objects and Arrays). The basic structure for function calls with f is the following;

let fn = f('route/to/function');
fn(arg_1, ..., arg_n, {kwarg_1: val_1, ... kwarg_n: val_n}, callback);

This maps to an HTTP request with the following POST data in the body;

{
	"args": [arg_1, ..., arg_n],
	"kwargs": {
		"kwarg_1": val_1,
		...
		"kwarg_n": val_n
	}
}

Which should be interpreted by a functional microservice (server-side) as;

module.exports = (params, callback) => {
	// params.args == [arg_1, ..., arg_n]
	// params.kwargs == {kwarg_1: val_1, ..., kwarg_n: val_n}
	callback(null, 'Hello World');
};

Note that every parameter is optional. It's up to whoever creates the microservice to lay out the expectation of which arguments / keyword arguments are supported, which can be done using descriptions on services like stdlib or GitHub.

Sending Files

To send raw file (Buffer) data, simply provide 'file' as a string to the second argument when referencing the function:

f('path/to/func', 'file')(new Buffer(0), callback);

This will send POST data with exactly the Buffer contents.

Configuring Gateway

If you don't feel like using stdlib's gateway at https://f.stdlib.com/, simply configure the gateway as follows;

const f = require('f');
f.config.gateway = {
	host: 'my.host',
	port: 8080,
	path: '/'
};

You can, alternatively, pass in custom configuration as a third parameter on a per-function basis.

let fn = f('path/to/func', 'json', {host: 'my.host', port: 8080, path: '/'});
fn(arg0, ..., callback);

Why Use Microservices?

Microservices are tremendously useful for offloading computationally expensive tasks from your core infrastructure, or providing standardized functionality to many different systems (at the cost of a few ms of network latency).

An example would be image processing. Resizing, cropping and editing may not be done frequently on your webserver, but when it does happen, it can slow everything down. Offloading to a scalable, stateless microservice that your application simply calls via the f module is a simple solution.

Another example would be the haversine distance formula given above. You may have found a great npm package, but what if that service functionality needs to be shared across multiple applications written in different languages? Python and Ruby are both capable of making simple HTTP requests to a microservice, but do not share packages in common with the Node ecosystem. Microservices solve this problem.

We plan to have more SDKs out in the coming months. :)

Where can I find Microservices to use?

You can find a list of available microservices on stdlib's search page, where the f team (Polybit Inc.) is hard at work creating a central registry of microservices for the web. Feel free to test drive a basic service or create your own.

You can create microservices using the stdlib CLI tools, but microservice development is out of the scope of the f package directly. It is handled on a platform and infrastructure provider basis.

Thanks!

The f package is © 2016 Polybit Inc. and happily MIT licensed.

Go wild! Contributors welcome, but we ask that PRs don't introduce dependencies and mostly focus on bugfixes and usability.

Sign up for stdlib: A Standard Library for Microservices.

Follow us on Twitter @polybit.