Page authors

Site owners

Concepts

A key concept of REST, as it underpins the web, is that URLs name resources. For static sites this is clear, and even for dynamic sites, the URLs we show users generally name resources within the web application the user can name.

In most modern programming, similar concepts prevails: We use references to objects as the means through which we manipulate them. In general, we prefer not to have global static functions that take pointers to data to operate on. There are many reasons for this: insulation, reusability, inheritance, composition, modularity, etc.

However, common practice for HTTP APIs is for URLs to name verbs. The resources on which those verbs act must be provided, and validated, in the arguments to the request. While sometimes, like in programming, a global static name for a function is the right choice, using this style for everything can lead to an awkward interface, and can be error prone.

Belay takes concepts from programming, and extends them to URLs giving us truly REST APIs: A BCAP URL is a reference to a particular data object and web handler that functions the same as object reference in a programming language.

For example: To model a blog that had entries, each of which can have comments, in JAVA, you might expect to see this:

public class Comment {

public String text;

public Date when;

}

public class Item {

public String title;

public String text;

public Date when;

public List<Comment> getComments() { ... }

}

public class Blog {

public String title;

public List<Item> getItems() { ... }

}

This example is admittedly very simplistic, but it demonstrates the key modeling concept: We use a call on Blog to retrieve references to the items, then a call on each Item to retrieve references to Comments. On the other hand, if we saw this version, we'd probably raise an eyebrow:

And yet, this is precisely the kind of modeling that most REST APIs offer. Belay let's one create an API that matches the first model: Each time a reference needs to be returned, a grant is made, which generates a new BCAP URL, and binds that URL to the particular data item and interface for it. When the client of the API get's this URL, when it wants to access that interface (such as get the item data), it simply does GET or POST to it as appropriate. The JSON returned may, like any good OO API, contain yet more such references to other objects (say, a list of BCAPs, one for each comment.)