Working with a Hypermedia (REST) API in Backbone

Question

In the process of building a Backbone.js SPA that talks to a RESTful (hopefully) API. I've tried to design the API around resources, using hypermedia to link the resources together. As I've begun implementing things in Backbone, I'm starting to realize that accomplishing true hypermedia with Backbone may not be a good fit.

The main issue is backbone routers wanting to have their paths declared up-front. With a good Hypermedia API, resource URIs should not be hard-coded in the client, to allow for flexibility in adding new features and (gasp) changing resource locations.

I'm playing with the idea of decoupling client-level Page Resources from API-level Object Resources. Somebody scream if this is nuts. Basically, this would mean defining routes to resources within my backbone app (think a discrete page), which would then retrieve one or more API-level resources.

This leads to some interesting questions:

Is this even a good idea? Should I do my best to re-use the API-level resource URIs within my app such that the routes are 1-to-1.
- I realize that a page and an api object are just different representations of the same resource, but in most cases, a page is a composite of multiple resources. Or I'm just crazy :)
What happens with page-refreshes in the middle of a series of navigations. How do I know the location of the API-level resources if they aren't the same?
It seems to me that RESTful design emphasizes discovery over knowing things up front. Am I right in assuming this? Is this what code download is all about? Can someone point me to further reading if I'm going the right direction.

Most of the resources are read-only, and so only use the GET verb, but I do have a few scenarios that use POST/PUT (DELETE really isn't in the domain of this particular client, except for possibly aborting an order before it's placed fully).

*Let me just say that I am by no means a REST guru. I'm still in the process of learning, so feel free to tell me I'm off base completely. No feelings will be hurt.

Edit:

I've been thinking more about code download in relationship to SPAs. A few more options:

Define your resource URIs in an 'API' resource or similar, that is loaded dynamically (code download). Here's an example:

// this object downloaded along with the application code, on a refresh
Framework.API.Resources = {
    Tasks: {
        uri: '/tasks',
        rel: 'self'
    },
    Users: {
        uri: '/users',
        rel: 'self'
    },
    // ... etc
}

// then in a collection

var TaskCollection = Backbone.Collection.extend(
    uri: Framework.API.Resources.Tasks.uri
    // implementation details
);

Dynamically define your routes as you navigate through resources, using the "root" resource uri as your route. I believe this is possible with Backbone.Router.route, but I'm not sure if it's possible to do on-the-fly. Has anyone tried this?

score 1 · Answer 1 · answered Jul 25 '12 at 15:05

1

Re #3

Real world examples of code on demand are hard to find and I haven't found a reason to do it yet.

I think of discovery in 2 places. 1) Upfront discovery that you can then code to. So for example every browser knows they will be processing HTML and can design up front for media type. 2) Runtime discovery, Although browsers know what they need to process, they don't know what is in those messages. They have the mechanisms for moving though hypermedia done, but will discover the execution of it during runtime.

In an app I'm working on. We used design time discovery to look at the documentation of the REST API. This API details all the possible link relations, media types and hypermedia. We coded the client based on all possible hypermedia. During runtime we checked to see if they were available based on if the hypermedia exist or not.

I see no reason why your SPA and pages need to be 1-1 with resources. One of the priciples of REST is that it is Client --> Server and therefore they can evolve differently. If you get a design benefit of making them 1-1 then that's your choice.

answered Jul 25 '12 at 15:05

suing

2,808
2
16
18

That makes sense. How, then, do you handle URIs on the client? If the client needs to be aware of all possible URIs, what is the benefit of hypermedia? I suppose it would still allow evolution of an application and a simpler programming model, but I would really prefer dynamic discovery of URIs, based on known resource types. – Jon Wingfield Jul 25 '12 at 16:11
It allows the URI's to change and it allows new ones to be added. It isn't the dynamic discovery you are looking for. I look at the way browsers handle it. The MediaType HTML has a rich set of metadata (
) that comes with the hypermedia explaining how to use it. I feel that's very difficult when not using HTML. Even a simple get with variables in the URI is hard to do dynamically because have to know what the template is at least. Also remember a human is involved in web browses where they might not be for your system.
– suing Jul 25 '12 at 20:08
The benefit is that it's still critical for our HATEOAS. If a link is there the machine knows it can move in that direction if it's not then it cannot and must choose a different path. – suing Jul 25 '12 at 20:17
I'm not so sure that it isn't about dynamic discovery. (Don't take this as argumentative, I'm still learning) "A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations." – Jon Wingfield Jul 25 '12 at 20:49
Most of us are learning :) HTML does dynamic discovery. I would say that ATOM or RSS do as well. Though ATOM and RSS are very simple. For us we breached the simple stuff early on and it would be difficult to produce a client without prior knowledge of usage. – suing Jul 25 '12 at 21:09
Yes. It seems that whenever non-human clients are mentioned, you end up with some sort of reference to code download in order to be able to effectively navigate a set of resources. – Jon Wingfield Jul 25 '12 at 21:22

score 0 · Answer 2 · answered Jul 25 '12 at 13:35

0

While that was the intention of REST as described by Roy Fielding, I don't think we're there yet in our frameworks, Backbone.js included. The javascript frameworks nowadays, it seems to me, are assuming that there is a one-to-one mapping of with the remote resources. Personally, I would not try to implement Hypermedia in Backbone.js

answered Jul 25 '12 at 13:35

Paolo del Mundo

2,121
13
18

I'm OK with the one-to-one mapping. A resource can be easily represented with a backbone model, for instance. The problem is that coupling with the resources _location_. – Jon Wingfield Jul 25 '12 at 14:42

Working with a Hypermedia (REST) API in Backbone

2 Answers2