Coming up!

• Architecture of an API backed JavaScript application
• Building JSON RESTful APIs
• A quick look at Backbone.JS
• A client framework built on top of Backbone supporting hyperlinks and data binding in views.

A rich JavaScript application

• Dharmafly have been building a rich JavaScript collaboration application for a client. We built it starting with a Hypermedia API and then building a Backbone.JS based rich JavaScript (CoffeeScript, actually) application to talk to it.

The Dharmafly Team

Technologies

Architecture

The RESTful API

RESTful APIs

• Based resources (nouns), not on actions (verbs).
• Accessed via a uniform interface (use the HTTP verbs)
• Hyperlinked resources (like links on web pages, but entirely for machine consumption)
• Self describing (less specific stuff in your code!)

A RESTful API

• GET: Just get a resource.
• PUT: Update a resource.
• DELETE: Delete a resource
• POST: Create a resource

• Resources not actions
• Uniform interface
• Hyperlinked!

HTTP is Cool

• Set of standard response codes: 200, 201, 404, 500 etc
• Compression
• Authentication
• Caching
• Content negotiation
• Encryption
• More!

Idempotent, Safe, etc

Idempotent is a big word, but it just means that doing something lots is the same as doing it once. So automatic retries are fine!

Representation

• Popular choices are XML or JSON
• Ideally we'd use existing standards, but sometimes there aren't ones that fit
• We based our representation form on JSON but added some structure and conventions.

Hyperlinks in JSON

• Hyperlinks are represented by a object with a "href" key.

{
  "href": "http://example.com/api/v1/users/john",
} 

Structure for JSON

• JSON itself lacks structure. So we add some on top.

{
  "href": "http://example.com/api/v1/users/john",
  "type": "user",
  "head": {
    ...
  },
  "body": {
   ...
  }
}
      

Related Links

• Each resource has a set of related links.

{
  "href": "http://example.com/api/v1/users/john",
  "type": "user",
  "head": {
    ...
    "related": {
      "meetings": {
        "href": "http://example.com/api/v1/users/john/meetings"
      }
    }
  },
  "body": {
    ...
  }
}

Resource Representations

{
  "href": "http://example.com/api/v1/users/john",
  "type": "user",
  "head": {
    "allow": ["GET","PUT","PATCH","DELETE"],
    "created_at": "2011-03-09T00:33:00Z",
    "updated_at": "2011-03-09T00:33:00Z",
    "related": {
      "meetings": {
        "href": "http://example.com/api/v1/users/john/meetings"
      }
    }
  },
  "body": {
    "display_name": "John Doe",
    "phone_number": "123456789",
    "email": "john@example.com",
  }
}

Example: Interacting with a meeting

• Get meeting

  GET http://example.com/api/v1/meetings/MEETINGID
  
  RESPONSE:
  HTTP 200 OK
  {
     "href": "http://example.com/api/v1/meetings/MEETINGID",
     "type": "meeting",
     "head": {...},
     "body": {...}
  } 

• Update meeting
• Delete meeting
• Create meeting

Example: Interacting with a meeting

• Get meeting
• Update meeting

  PUT http://example.com/api/v1/meetings/MEETINGID
  {
    "body": {
      "title": "My awesome meeting"
      ....
    }
  }
  
  RESPONSE:
  HTTP 200 OK
  {
     "href": "http://example.com/api/v1/meetings/MEETINGID",
     "type": "meeting",
     "head": {...},
     "body": {
       "title": "My awesome meeting"
       ....
     }
  } 

• Delete meeting
• Create meeting

Example: Interacting with a meeting

• Get meeting
• Update meeting
• Delete meeting

  DELETE http://example.com/api/v1/meetings/MEETINGID
  
  RESPONSE:
  HTTP 204 No Content 

• Create meeting

Example: Interacting with a meeting

• Get meeting
• Update meeting
• Delete meeting
• Create meeting

  POST http://example.com/api/v1/users/USERID/meetings
  {
    "body": {
      "title": "My new meeting"
      ....
    }
  }
  
  RESPONSE:
  HTTP 201 Created
  Location: http://example.com/api/v1/meetings/NEWMEETINGID 

Live Updates with WebSockets

• We want live updates to resources to support live chat and presentations. Looks like a job for WebSockets!
• Meeting links to WebSocket endpoint

  ws://example.com/api/v1/meetings/MYMEETING

• Client connects to endpoint
• Server streams down resource representations as they change

{
 "type": "comment",
 "href": "http://example.com/api/v1/meetings/MYMEETING/activities/99",
 "head": {
  "related": {
   "parent": {
    "href": "http://example.com/api/v1/meetings/MEETINGID/activities"
   }
  }
 },
 "body": {
  "text": "Hello world!"
 }
} 

Partial Updates with PATCH and JSONPatch

• How to do partial updates with REST?
• One option: PATCH verb and JSONPatch format

Example resource:

{
  "type": "conference",
  "href": "http://example.com/api/v1/conferences/CONFERENCEID",
  "head": {
     ...
  },
  "body": {
    "lecture_mode": false,
    "recording": false,
    "locked": false
  }
} 

JSONPatch to start recording:

PATCH http://example.com/api/v1/conferences/CONFERENCEID
[
    {"replace": "/body/recording", "value": true},
] 

Demo here: The API

A Quick Intro to Backbone.JS

Backbone.JS

• MVC on the client (or MVP or MV*, whatever)
• Provides Models, Collections, Views and a Router
• Models and Collections emit events when they change
• Views are mainly convention
• The router uses either hashes or the HTML5 History API

Backbone.JS Model Example

TodoModel = Backbone.Model.extend({
  defaults: {
    done: false,
    title: 'Todo item'
  }
});
 
var model = new TodoModel({title: 'Do stuff'});

model.on('change:title', function () {
  alert('Title is now: ' + model.get('title'));
});

model.set({title: 'Do other stuff'}); 

Backbone.JS View Example

var TodoView = Backbone.View.extend({
  events: {'click': 'updateDone'},
  initialize: function () {
    this.model.on('change', this.render, this);
  },
  render: function () {
    this.$el.html('<input type="checkbox"/><b></b>');
    this.$('input').attr('checked',this.model.get('done'));
    this.$('b').text(this.model.get('title'));
  },
  updateDone: function () {
    this.model.set('done', !this.model.get('done'));
  }
});

var view = new TodoView({model: model});
view.render();

$('#todo-items').append(view.el); 

Backbone.JS Collection Example

var todoitems = new Backbone.Collection();

todoitems.on('add', function (added) {
  alert('Todo item added with title: ' + added.get('title'));
});

todoitems.add(model);
  

JavaScript Client App

Models in the App

• No special per-resource model classes
• An identity map. Always same instance for given URL
• Linking and inclusion handled nicely
• Collections are just a type of model

Getting a resource model

# Create a client instance (usually once per app)
client = new resources.Client({
  base: "http://example.com/api/v1/"
});

# Get a resource from a known url. If the resource exists in the cache
# it will be returned.
meeting = client.getResource(
   'http://example.com/api/v1/meetings/MEETINGID'
);
  

Making sure a resource is loaded

# Make sure the resource has been fetched from the server
# (only fetch if it hasn't already been fetched)
meeting.maybeFetch().done(function () {
  # It's now safe to assume that the meeting is loaded
  alert(meeting.get('title'));
});

  

Subscribe to a resource's stream

# Subscribe to the WebSocket stream for this meeting
meeting.subscribe(); 

Resource Hyperlinks

# Follow a "related" hyperlink
comments = meeting.related('comments');

# Fetch each item in a collection. If there where inclusions
# instead of links this doesn't actually go to the server.
comments.fetchEach(function (comment) {
  alert('I have a fully loaded comment here:' + comment.get('text'));

  # Combines a call to related and to maybeFetch
  comment.fetchRelated('owner', function (user) {
    alert(user.get('name') + ' posted that comment');
  });
});

Views

• Backbone.JS's views are very minimal
• Handlebars templates
• Model binding
• View Hierarchy

Model Binding

• Bind model fields to context variables for the view
• Handles listening on the correct events
• All in a fairly declarative style

Model Binding

# Actual version is in CoffeeScript
var MeetingView = views.BaseView.extend({
  template: 'app/templates/meeting/meeting.html',
  contextBindings: {
    title: 'title',
    starts_at: 'starts_at',
    owner_name: 'owner/full_name'
  },
  ...
});
  

<div class="meeting">
  <h1>{{title}} at {{starts_at}} by {{owner_name}}</h1>
  <ul class="comments">
</ul> 
</div> 

View Hierarchy

• Templates that re-render every time are easy and flexible
• But not always efficient!
• View hierarchy lets us not re-render children just because parent changed.

View Hierarchy

var MeetingView = views.BaseView.extend({
...
attachPoints: {
  comment: '.comments'
}
});

var Comment = views.BaseView.extend({
...
});

# In a controller somewhere
mettingview.appendSubView(new Comment({model: commentModel}));

<div class="meeting">
<h1>{{title}} at {{starts_at}} by {{owner_name}}</h1>
<ul class="comments">
</ul> 
</div> 

Router

• A hierarchical router
• Each level of hierarchy has enter and leave handlers
• Moving between routes runs just the enter and leave handlers needed to make the move.
• A shared context allows each level to store values. But they're only visible from that level and up.

Router

Router

Router

Router

Router

Router

base = new router.Route()
meetingroute = base.extend('/meeting/:id', {
  enter: function (id) {
    // Assign stuff to the context in the enter function...
    this.view = createMeetingView();
  },
  leave: function () {
    //...and it's available in the leave function too
    this.view.destroy();
  }
});

Router: Sub-routes

# full path would now be /meeting/:id/summary
meetingroute.extend('/summary', {
  enter: function () {
    # We still have access to the view we set in the parent route
    this.view.showSummary();

    # this will be accessible to this route and all beneath it but
    # won't be visible to the parent route's handlers
    this.otherInfo = 'hello';
  },
  leave: function () {
    this.view.hideSummary();
  } 
});

Router: Asynchronous

base = new router.Route()
meetingroute = base.extend('/meeting/:id', {
  enter: function (id) {
    var _this = this;
    # return a promise as this isn't finished until
    # the meeting view is loaded. Actions after this
    # are queued until it's done
    return loadMeetingView(id).done(function (view) {
      _this.view = view; 
    });
  },
  leave: function () {
    this.view.destroy();
  }
});

Summary

• RESTful APIs are made up of hyperlinked resources
• Use the HTTP verbs, GET, PUT, DELETE, POST (+PATCH!) as a Uniform Interface
• We used a JSON representation with a the {"href": "http://example.com/resource"} convention for links.
• Links as a subset of full resources allows easy inclusions
• WebSockets to allow push updates
• A RESTful API can lead to more generic code and less specific code.

Thanks For Listening!

http://almostobsolete.net/talks/londonjs/

Thomas Parslow
tom@almostobsolete.net
@almostobsolete
http://almostobsolete.net