restfulness.info

Home of the Resource Oriented Enterprise

Home

 


Web's main abstraction
A Closer Look at the Resource

The Resource is one of the main abstractions of the Resource Oriented Enterprise and is of paramount importance. In the following, we give a short overview of the underlying ncepts.

For those familiar with object orientation, a Resource can be considered an object that

a) has an URI, i.e. is addressable

b) offers as an interface the request methods of HTTP (GET, POST, HEAD, PUT, DELETE, TRACE, OPTIONS)

c) represents an encapsulation of some data fragment and/or service. Has links.

d) returns some Hypertext format, most commonly HTML, many XML document types such XHTML or ATOM, or binary types like PDF or image formats.

The following image depicts these properties:


The Resource is the central abstraction in a Resource Oriented Enterprise

Addressability

From an Information Requester's point of view, the Resource is the target of his HTTP request. Addressability is perhaps the single most important quality of a Resource. Without it, we would not be able to span an addressing system over the enterprise.

The address is an Uniform Resource Identifier (URI) that uniquely denotes the resource in the enterprise, or more precisely, within the DNS addressing space.

The URI specs (RFC 1630/3986) emphasize that an URI can also point to resources that do not (yet) exist or are not information objects, e.g. physical objects like machines or buildings. Thus,

/privateCustomers/334455

would, combined with an HTTP PUT command, create a new private customer, if it not yet existed. And

/assets/building3/room1003/photocopier

points to the photocopier in room 1003 in building 3 of the ROE, independent of the make and type of the machine.

Uniform interface

One of the strength of REST is that it works with a minimal, but extremely well defined API for resources. That API is mandated by the HTTP protocol. Whereas HTTP GETs and POSTs are common place due to their support by web browsers, HEAD, PUT and DELETE are rarely used, while TRACE and OPTIONS are almost unknown to the general public. The Wikipedia page on HTTP provides a fairly good overview of what these commands do.

The main point from the Resource Oriented Enterprise's perspective is that this small set of commands enables extreme polymorphism. Whatever the resource is, a client can assume that it supports these methods. This opens room for very flexible, really loosely coupled systems that can react quickly on business and technical events.

Encapsulates data, services, and links

Resources can represent virtually everything, from very small to huge, from simple to complex. A resource can represent an entire organisational division of the ROE with thousands of customers and employees, or something tiny like cell C12 in some spreadsheet. In the background, there might be complex integration services required to satisfy requests to the resource, or it represents a simple database record.

Thus, as any object, a Resource has some sort of implementation. In consequence, there is no central monolithic code block, but resources can react very specifically and agile on requests.

Resources don't live on their own. They have context. And often, it is the context that gives meaning to them. Thus, links are the central element in the architecture that add the flexibility we are so badly in need of. Frequently, links to other resources denote the state of a Resource.

Returns hypertext representation

A Resource not only supports an uniform interface, but replies in a generic format that can be understood by many clients, and that's hypertext.

Think about hypertext and being a text format such RTF plus hyperlinks pointing to other resources. These hyperlinks represent the links we mentioned in the previous chapter.

So, if REST talks about representation, it means a hypermedia format that cotains a resource's current state and the hyperlinks describe the resources current context. Hypertext is also chosen, because it can be understood by many clients, browsers and parsers for machine readability. The representation format is requested by the client, and the server should satisfy the format if possible.

Of course, there are also non-hypermedia formats, such as graphics formats. Coming back to the above copier example,

/assets/building3/room1003/photocopier/picture

would point to some picture of the photocopier. The representation is requested by the client through a MIME type like "picture.jpg" or the HTTP Accept header.