Restful Bmtn

Restful Blue Mountain

This document is a sketchbook for developing a RESTful interface to the Blue Mountain resource.

Modeling

One tenet of RESTful architecture is modeling your entities – magazines, issues, contributors, articles, images, pages, etc. – as resources.

The first step in modeling your entities as resources on the web is to give them identifiers, so they can be addressed and manipulated. We have already implemented a scheme of URIs for our magazine enties, and these will form the foundation for our model. (The syntax for these URIs is detailed in the Reference document in this wiki.)

For example, the first issue of Action, published in February of 1920, has the following unique identifier:

urn:PUL:periodicals:bluemountain:bmtnaab_1920-02_01

This is not the place to describe the difference between URIs, URNs, and URLs (there are plenty of explanations available on the web and in books); it is enough to remember that URNs are Uniform Resource Names and URLs are Uniform Resource Locators, and that both are kinds of URIs: Uniform Resource Identifiers. A URN, that is, is a name, and a URL is a place: urn:PUL:periodicals:bluemountain:bmtnaab_1920-02_01 is the name of the resource (Blue Mountain’s digital edition of the first issue of Action). It is not a URL; it does not say where to find it: that is, you can’t type urn:PUL:periodicals:bluemountain:bmtnaab_1920-02_01 into your web browser and expect to see the cover of the issue pop up. That’s because the location of the resource may change.

How, then, can you use a URN to find a resource?

That is the job of a resolver algorithm, which may be as simple as replacing a few colons with slashes:

http://library.princeton.edu/periodicals/bluemountain.princeton.edu/bmtnaab_1920-02_01

but will more likely be a bit more sophisticated.

bluemountain.princeton.edu/issues/bmtnaab/1920/02/_01

Designing a Resource-Oriented Architecture

Richardson & Ruby’s Restful Web Services is a well-respected introduction to designing and implementing Resource-Oriented systems. In Chapter 5, they suggest the following procedure for designing a set of resources that can then be implemented via HTTP’s read-only interface (GET and HEAD). For now, that will be a sufficient design constraint for Blue Mountain.

Here’s the procedure:

1. Figure out the data set
2. Split the data set into resources
3. Name the resources with URIs
4. Expose a subset of the uniform interface
5. Design the representation(s) accepted from the client
6. Design the representation(s) served to the client
7. Integrate this resource into existing resources, using hypermedia links and forms
8. Consider the typical course of events: what’s supposed to happen?
9. Consider error condtions: what might go wrong?

In what follows, Im going to follow this procedure to design Blue Mountain’s resource-oriented interface.

Figure out the service

What is Blue Mountain Springs supposed to do? It is the service here.

Figure out the data set

Our data set is issues of magazines. Blue Mountain Springs will serve up issues of magazines in different forms: as page images, as machine-readable transcriptions.

The data set contains magazine issues, but also representations of the magazines themselves: the abstract entities.

Split the data set into resources

Richardson and Ruby suggest web services typically expose three kinds of resources:

1. Pre-defined one-off resources :: like portal pages; top-level directories of other available resources.
2. A resource for every object exposed through the service
3. Algorithmic resources :: “collection resources, which are usually the result of queries.”

Here’s the beginning of a list of resources:

• List of magazine titles
• Broom (a specific title)
• The issues of a magazine
  • within some date range
• A particular issue
• The constituents of a particular issue
• The constituents of an entire magazine run
• The ads in a particular issue, etc.
• The text of a particular article
• The digital reproduction of a drawing, print, or other graphical printed constituent.
• The digital reproduction of some page or set of pages, or portions of pages.
• The third word of the fifth paragraph of a particular article.
• The contributions of a particular creator

So far, these resources resemble the map resources Richardson & Ruby describe in their book.

Name the resources

Guidance from Richardson & Ruby:

1. Use path names to represent hierarchies; commas or semicolons to represent non-hierarchical concepts, scoping information. Don’t force everything into hierarchies!
2. Use query variables for algorithmic resources.

Now for some names:

• /periodicals
• /issues
• /pages
• /contributors
• /titles
• /constituents
• /creators

Richardson & Ruby point out that a resource may have more than one URI. This can “dilute” the value of each individual URI. One solution is to designate one URI as the “canonical” URI for the resource, and then redirect via HTTP 303 header.

Structure Maps as Resources?

Our structMaps have divs of specific types, corresponding to the content model described by our docWorks configuration. Those divs should be resources.

Working on the content negotiation bit

The separation of concerns should entail putting the results of the query into the model and then calling a view based on the content type requested. Jon Stroop has done work with this for PULFA; see his code on GitHub.