restinga

restinga-node

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

Contents

• Usage
• Overview
• Debug
• Docs
  • Resource Methods
  • Make Your Auth System
  • Make Your Format

Usage

npm install -S restinga

Overview

digital-ocean-descriptor.js

import {Descriptor} from 'restinga';
import {Bearer} from 'restinga/lib/auth';
 
export default class DigitalOceanDescriptor extends Descriptor {
  constructor() {
    super({
      service: 'digital-ocean',
      prefix: 'https://api.digitalocean.com/v2',
      
      // Optional User-Agent for requests:
      agent: 'restinga-node/1.0.0 (https://github.com/jay-ess/restinga-node)'
    });
  }
  
  // Optional auth setup
  get authorization() {
    return new Bearer('YourToken');
  }
}

container.js

import {Container} from 'restinga';
import DigitalOceanDescriptor from './digital-ocean-descriptor';
 
Container.register(new DigitalOceanDescriptor());

droplet.js

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

usage.js

import Droplet from './droplet';
 
const droplet = new Droplet({
  name: 'server.restinga.dev',
  region: 'nyc3',
  size: '512mb',
  image: 'ubuntu-14-04-x64'
});
 
// Resources methods return Promises
 
droplet.save()
  .then(droplet => console.log(droplet.get('id'))) // Returns itself
  .catch(err => console.log(err));
 
// Wanna some async-await?
 
try {
  await droplet.save();
  console.log(droplet.get('id'));
} catch (err) {
  console.log(err);
}

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

Debug

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.

Docs

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

License

MIT