Ultra flexible api client. Never write a REST Client again!
Last updated 2 years ago by hyvemynd .
ISC · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install proteus-client 
SYNC missed versions from official npm registry.


Ultra flexible api client. Never write a REST Client again!

In Greek mythology, Proteus is an early sea-god or god of rivers and oceanic bodies of water, ... of "versatile", "mutable", "capable of assuming many forms". "Protean" has positive connotations of flexibility, versatility and adaptability.


Proteus is the REST client to end all rest clients. It allows an app developer to idiomatically make REST calls without all the boilerplate. Leveraging node-fetch which relies on the wonderful fetch polyfill, Proteus is easy-to-use and allows you, the developer, to focus on more important problems.


npm i -S proteus-client


Create a Proteus client with a baseUrl. Then simply chain resource endpoints togehter to dynamically build your REST endpoint URL. Lastly, call fetch in order to execute the request. By leveraging node-fetch, the Proteus api will be very familiar to anyone who has developed with Github's fetch API.

const Proteus = require('Proteus');
const api = new Proteus('');

  .then(response => response.json())
  .then(json => console.log(json));

// Outputs the following
  "id": 1,
  "name": "Leanne Graham",
  "username": "Bret",
  "email": "",
  "address": {
    "street": "Kulas Light",
    "suite": "Apt. 556",
    "city": "Gwenborough",
    "zipcode": "92998-3874",
    "geo": {
      "lat": "-37.3159",
      "lng": "81.1496"
  "phone": "1-770-736-8031 x56442",
  "website": "",
  "company": {
    "name": "Romaguera-Crona",
    "catchPhrase": "Multi-layered client-server neural-net",
    "bs": "harness real-time e-markets"

How it works

Proteus will read the object invocations and convert those into a REST endpoint to call. The name of the function being called will translate to a single path on the url. In order to provide a url parameter, simply provide an argument to the function (NOTE: must be coercable into a string).

const api = new Proteus('https://localhost');

// Makes a GET request to https://localhost/users/1/addresses

// Makes a GET request to https://localhost/path/my-id/to/my/resource


Node-Fetch API

The final call to the call chain in Proteus is fetch. The fetch call follows mostly (adapted for node and this project) the same api. Please see node-fetch for more detail about features made possible by Node.js.

new Proteus(baseUrl)

  • baseUrl A string representing the base URL for the fetch request
  • Returns: Proteus instance

Create a new instance of Proteus.

baseUrl should be an absolute url, such as A path-relative URL (/file/under/root) or protocol-relative URL (// will result in a rejected promise.


  • key The name provided will resolve into a url path.
  • param The value of param will resolve into the next part of the url path following the key
  • Returns: Proteus

Builds the URL to fetch. Chainable to build more complex URLs.


const proteusInstance = new Proteus('http://localhost');

// http://localhost/users

// http://localhost/users/1/addresses

// http://localhost/buildings/502/floors/2/wings/west/rooms/213/desks/10/chairs/a


Perform an HTTP(S) fetch.


Shorthand to perform an HTTP(S) fetch using the GET verb.


Shorthand to perform an HTTP(S) fetch using the POST verb.


Shorthand to perform an HTTP(S) fetch using the PUT verb.


Shorthand to perform an HTTP(S) fetch using the PATCH verb.


Shorthand to perform an HTTP(S) fetch using the DELETE verb.


The default values are shown after each option key.

	// These properties are part of the Fetch Standard
	method: 'GET',
	headers: {},        // request headers. format is the identical to that accepted by the Headers constructor (see below)
	body: null,         // request body. can be null, a string, a Buffer, a Blob, or a Node.js Readable stream
	redirect: 'follow', // set to `manual` to extract redirect headers, `error` to reject redirect

	// The following properties are node-fetch extensions
	follow: 20,         // maximum redirect count. 0 to not follow redirect
	timeout: 0,         // req/res timeout in ms, it resets on redirect. 0 to disable (OS limit applies)
	compress: true,     // support gzip/deflate content encoding. false to disable
	size: 0,            // maximum response body size in bytes. 0 to disable
	agent: null         // http(s).Agent instance, allows custom proxy, certificate etc.

	// These properties are Proteus extensions
	query: null,        // map of key:value pairs for query parameters
Default Headers

If no values are set, the following request headers will be sent automatically:

Header Value
Accept-Encoding gzip,deflate (when options.compress === true)
Accept */*
Connection close (when no options.agent is present)
Content-Length (automatically calculated, if possible)
User-Agent node-fetch/1.0 (+

Current Tags

  • 0.3.1                                ...           latest (2 years ago)

9 Versions

  • 0.3.1                                ...           2 years ago
  • 0.3.0                                ...           2 years ago
  • 0.2.7                                ...           2 years ago
  • 0.2.6                                ...           2 years ago
  • 0.2.4                                ...           3 years ago
  • 0.2.3                                ...           3 years ago
  • 0.2.2                                ...           3 years ago
  • 0.2.0                                ...           3 years ago
  • 0.1.0                                ...           3 years ago
Maintainers (1)
Today 0
This Week 0
This Month 19
Last Day 0
Last Week 0
Last Month 1
Dependencies (2)
Dependents (0)

Copyright 2014 - 2016 © |