runnable-api-client

Runnable Api Client

Usage

Users

Tokenless

var user = new Runnable();

Github Login

var user = new Runnable();

user.githubLogin(function (err, body) {
  // ...
});

Github Token Login

var user = new Runnable();

user.githubLogin(token, function (err, body) {
  // ...
});

Logout

var user = new Runnable();

user.logout('user', 'pass', function (err, body) {
  // ...
});

Resources

First level resource (projects)

var user = new Runnable();

user.login('user', 'pass', function (err, body) {
  // fetch a specific resource
  var project = user.fetchProject(projectId, function (err, body, code) {
    // project becomes a project model
  });
  // factory methods and parent actions
  project = user.newProject(attrs, opts);
  project = user.fetchProject(projectId, cb);
  project = user.createProject({ json: data }, cb);
  project = user.updateProject(projectId, { json: data }, cb);
  user.destroyProject(projectId, cb);
  // model methods
  project.fetch(cb); // fetch latest
  project.update({ json: attrs }, cb); // update the resource attrs
  project.destroy(cb); // delete the resource through the api
  project.toJSON(); // last clientside known state of the resource

  // fetch a collection of resources
  var projects = user.fetchProjects(projectId, function (err, body, code) {
    // project becomes a collection of projects
  });
  projects.models; // are all models of the resources fetched
});

Development

How to add a Model

Runnable api client's directory structure follows the api url structure and the structure of our resources.

Example - Adding a model for project environments:

Project environments are a nested resource - /projects/:id/environments/:id

Create a new file - lib/models/project/environment.js

Note: the singular form of each resource used for the folder and file names.

'use strict';

var util = require('util');
var Base = require('../base');
var urlJoin = require('../../url-join');

module.exports = Environment;

function Environment (attr, opts) {
  opts = opts || {};
  opts.urlPath = urlJoin(opts.parentPath, 'environments');
  return Base.apply(this, arguments);
}

util.inherits(Environment, Base);

All (99%) of the new models will inherit from the Base Model class like the example above. Nested Models use urlJoin(opts.parentPath, <relativePath>) create their urlPath using opts.parentPath. opts are being passed to the constructor from extend-with-factories which is explained below. First level resources like Projects (/projects), just need their urlPath set directly Projects.prototype.urlPath = 'projects' or opts.urlPath = 'projects'.

Update the parent model Class - lib/models/project.js

The parent model in this example is Project. Here is the Project Class:

var util = require('util');
var Base = require('./base');

module.exports = Project;

function Project () {
  return Base.apply(this, arguments);
}

util.inherits(Project, Base);

Project.prototype.urlPath = 'projects';

Add the following line to the parent model to automagically create submodel factory/action methods:

require('../extend-with-factories')(Project);

Example usage of the newly created environment model

var projectId = "real-project-id";
var user = new Runnable(), environment;

user.anonymous(function (err) {
  if (err) { throw err; }

  var project = user.fetchProject(projectId, function (err) {
    if (err) { throw err; }

    // automagical environment factory methods:
    environment = project.newEnvironment(attrs, opts);  // create a new environment instance
    environment = project.fetchEnvironment(projectId, cb); // fetches an environment instance from the api server
    environment = project.createEnvironment({ json: attrs }, cb); // makes a post request to create a new environment
    // automagical environment action methods:
    project.updateEnvironment(projectId, { json: attrs }, cb);
    project.destroyEnvironment(projectId, cb);

    // Action methods inherited by the Base Model
    environment.fetch(cb); // get latest data from server
    environment.update({ json: attrs }, cb);
    environment.destroy(cb);
  });
});

How to add a Collection

Creating a collection is very similar to the model example. The only difference is that you should inherit from the Base collection. Also, factory methods created use the plural form of the resource name - Ex: project.getEnvironments(cb). There are examples of all types of models and collections (first level and nested), when in doubt look for an existing example in the code base.