Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Build api wrappers around RESTful endpoints
JavaScript
branch: master
Failed to load latest commit information.
dist
examples
lib
test Make it so
.gitignore Initial commit
.npmignore Make it so
Gruntfile.js Make it so
LICENSE
README.md
bower.json
package.json

README.md

Narrator

Build api wrappers around RESTful endpoints. Now compatible with AngularJS and Browserify!

Install

On the server

npm install narrator --save

In the browser

bower install narrator --save

Usage

var Narrator = require('narrator');

var api = new Narrator({
  host: 'http://someendpoint.com'
});

// This will construct http://someendpoint.com/endpoint
var users = api.endpoint('users', {
  customMethod: function () {
    // You can have custom functionality
  }
});

users.list(function (err, usersList) {

});

// OR

// With promises
users.create({name: 'frank'}).then(function (response) {
  // User created
});

// OR

users.customMethod();

// AND

var user = users.one(123);
user.get(function (err, userData) {

});

Also, see Narrator Examples

Angular Module

angular.module('myApp', ['narrator'])
  .config(function (narratorProvider) {
    narratorProvider.configure({
      host: 'http://someapi.com',
      headers: {}
      // etc. Supports all $http config options
    });
  }).controller('SomeCtrl', function ($scope, narrator) {

    $scope.users = narrator.endpoint('users').list();

  });

XHR Arguments

The Angular module provides special methods to set custom xhr arguments. They conform to the $http arguments usage.

angular.module('myApp')
  .controller('SomeController', function ($scope, narrator) {

    narrator.withCredentials(true);

    // or
    narrator.xhr('withCredentials', true);

  });

Promises or Callbacks

All methods return a promise or allow you to provide a callback. For example:

api.endpoint('users').list().then(function (users) {

}, function (err) {

});

// OR

api.endpoint('users').list(function (err, users) {

});

Multi-item endpoint

Example:

var users = api.endpoint('users');

// users.url();
// users.list();
// users.create();
// users.one();
// users.getEndpoint();

url()

Returns the url for the current endpoint

list(callback)

Performs a GET request to the api for the given path name

  • callback - gets called with the arguments:
    • err - error object if one exists
    • response - the response from the server

create(payload, callback)

Performs a POST request to the api for the given path name

  • payload - the key-value object to send with the request
  • callback - gets called with the arguments:
    • err - error object if one exists
    • response - the response from the server

one(id)

Creates an new single item endpoint with the given id from the mult-item endpoint path. This method returns a new object with the single item methods (see below)

  • id - the id of the single item to create and endpoint form

getEndpoint(name [, id]);

Gets an endpoint by the endpoint pathname. If the endpoint you're getting is a singular item endpoint with and id, pass the id along.

  • name - the pathname of the endpoint
  • id - the id of the singular resource used when creating the path

Single-item endpoint

Example:

var users = api.endpoint('users');
var user = users.one(123); // Generats /user/123

// user.url();
// user.get();
// user.update();
// user.remove();
// user.endpoint();
// user.getEndpoint();

url()

Returns the url for the current endpoint

get(callback)

  • callback - gets called with the arguments:
    • err - error object if one exists
    • response - the response from the server

update(payload, callback)

  • payload - the key-value object to send with the request
  • callback - gets called with the arguments:
    • err - error object if one exists
    • response - the response from the server

remove(callback)

  • callback - gets called with the arguments:
    • err - error object if one exists
    • response - the response from the server

endpoint(name, customMethods)

This creates a new endpoint prefixed by the endpoint path that called this method. (i.e /users/123/comments). VERY helpful for creating nested endpoints.

  • name - the name of the endpoing, which is used to build the path (i.e. users creates the path /users)
  • customMethods - an object contain custom methods to add to the endpoint object

getEndpoint(name [, id]);

Gets an endpoint by the endpoint pathname. If the endpoint you're getting is a singular item endpoint with and id, pass the id along.

  • name - the pathname of the endpoint
  • id - the id of the singular resource used when creating the path

Run Tests

npm test
Something went wrong with that request. Please try again.