REST API abstraction layer to easily consume data. Based on artesaos/restinga
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


REST API abstraction layer to easily consume data. Based on artesaos/restinga.

Build Status Coverage Status XO code style



npm install -S restinga


import {Descriptor} from 'restinga';
import {Bearer} from 'restinga/lib/auth';

export default class DigitalOceanDescriptor extends Descriptor {
  constructor() {
      service: 'digital-ocean',
      prefix: '',
      // Optional User-Agent for requests:
      agent: 'restinga-node/1.0.0 ('
  // Optional auth setup
  get authorization() {
    return new Bearer('YourToken');
import {Container} from 'restinga';
import DigitalOceanDescriptor from './digital-ocean-descriptor';

Container.register(new DigitalOceanDescriptor());
import {Resource} from 'restinga';
import {receiveJson, sendJson} from 'restinga/lib/format';

export default class Droplet extends receiveJson(sendJson(Resource)) {
  setup() {
      service: 'digital-ocean', // match a descriptor service name
      name: 'droplets',
      identifier: 'id',
      collectionRoot: 'droplets',
      itemRoot: 'droplet'
import Droplet from './droplet';

const droplet = new Droplet({
  name: '',
  region: 'nyc3',
  size: '512mb',
  image: 'ubuntu-14-04-x64'

// Resources methods return Promises
  .then(droplet => console.log(droplet.get('id'))) // Returns itself
  .catch(err => console.log(err));

// Wanna some async-await?

try {
} catch (err) {

See a working example: test/resource.test.js.


Wanna know what's happening behind the scenes? This module uses visionmedia/debug, so you can just run DEBUG=restinga:* node your-file.js and get a pretty output of how restinga is working.


Resource methods

Method Return Type Description
hasParentResource() Boolean True if you're using a nested resource
childResource(resource) Resource Make a resource your child
getIdentifier() ?string Return the identifier value
get(key) * Return key from attributes
set(key, value) self Change a key from attributes
set(obj) self Change multiple attributes
unset(key) self Delete key from attributes
static all(query) Promise => Resource[] Static search resources
getAll(query) Promise => Resource[] Search resources
static find(identifier) Promise => Resource Static search for an resource with identifier = identifier
doFind(identifier) Promise => Resource Search for an resource with identifier = identifier
save() Promise => Resource Save this resource
update() Promise => Resource Update this resource
destroy() Promise Delete this resource

Make Your Auth System

For you to make your own authorization class, just make a class with a setupAuth() method that takes no params and returns an object like this:

class MyAuthSystem {
  setupRequest() {
    return {
      opts: {},
      headers: {}

opts follow http.request since we use got for requests. And headers are plain HTTP headers.

Make Your Format

Formats are High Order Classes that work as mixins and take care of understand what comes from your REST API responses.

To make a format, you must build receiveSomething() and sendSomething() mixins. See src/format/ for examples.

Receiver Methods:
Method Return Type Description
getAcceptHeader() string Value to the Accept HTTP header
factory(rawResponse) Resource Parse a resource and return it's instance
factoryCollection(rawResponse) Resource[] Parse multiple resources and returns an array of instances
Sender Methods:
Method Return Type Description
getContentTypeHeader() string Value to the Content-Type HTTP header
encode() * Do whatever you need with this.attributes before sendind it