## Protocol Details

### What is REST?

Representational State Transfer (REST) is a software architecture designed for distributed systems, like the World Wide Web. For details of the REST architecture and the philosophy underlying it, see the REST Wikipedia article.

One of the key concepts of a RESTful architecture is that the interaction between different network nodes should take on a very simple form. In particular, the number of operations in a RESTful protocol must be kept small: for example, the REST protocol in FUSE requires just three operations.

### Outline of a REST interaction

In general, a REST interaction consists of the following elements:

- Operation—belongs to a restricted, well-known set of operations—for example, in the HTTP protocol, the main operations are `GET`, `POST`, `PUT`, and `DELETE`. The advantage of this approach is that, in contrast to RPC architectures, there is no need to define interfaces for a RESTful protocol. The operations are all known in advance.

- URI—identifies the resource that the operation acts on. For example, a HTTP `GET` operation acts on the URI by fetching data from the resource identified by the URI.

- Data (if required)—needed for operations that send data to the remote resource.

### HTTP as a RESTful protocol

HTTP is a good example of a protocol demonstrating RESTful design principles. In fact, proponents of REST argue that it is precisely the RESTful qualities of HTTP that enabled the rapid expansion of the World Wide Web. In keeping with REST principles, HTTP has a restricted operation set, consisting of only eight operations: `GET`, `POST`, `PUT`, `DELETE`, `OPTIONS`, `HEAD`, `TRACE`, and `CONNECT`.

For the purpose of implementing a RESTful protocol, the first four HTTP operations—`GET`, `POST`, `PUT`, and `DELETE`—are the most important. The semantics of these operations are described briefly in Table 4.1 .

Table 4.1. HTTP RESTful Operations

Operation | Description
--- | ---
`GET` | Fetch the remote resource identified by the URI.
`POST` | Add/append/insert data to the remote resource identified by the URI.
`PUT` | Replace the remote resource identified by the URI with the data from this operation.
`DELETE` | Delete the remote resource identified by the URI.

This simple set of operations—analogous to the classic CRUD (Create, Replace, Update, and Delete) operations for a database—turns out to be remarkably powerful and flexible.

### REST protocol servlets

The following servlets—which are automatically deployed in the message broker Web console—implement RESTful access to the FUSE message queues:

- message servlet .

- queueBrowse servlet .

### message servlet

The RESTful service implemented by the FUSE `message` servlet enables you to enqueue and dequeue messages over HTTP. You can, therefore, use the message servlet to implement message producers and message consumers as Web forms.

To interact with the FUSE `message` servlet, construct a URL of the following form:

    http://Host:Port/WebContext/message/DestinationPath?Opt1=Val1&Opt2=Val2...

Where the URL is constructed from the following parts:

- `Host``:``Port`—the host and port of the servlet engine. For example, in the default message broker configuration, a HTTP port is opened on `localhost:8161`.

- `WebContext`—in a Web application, it is usual to group related components (servlets and so on) under a particular Web context, `WebContext`. For example, for the REST demonstration servlets, the Web context is `demo` by default.

- `message`—routes this URL to the `message` servlet.

- `DestinationPath`—specifies the compound name of a queue or topic in the message broker. For example, the `FOO.BAR` queue has the destination path, `FOO/BAR`.

- `?``Opt1``=``Val1``&``Opt2``=``Val2`—you can add some options in order to qualify how the URL is processed.

For example, the following URL can be used to fetch a message from the `FOO.BAR` queue, where the Web console has the default configuration:

    http://localhost:8161/demo/message/FOO/BAR?type=queue&timeout=5000

Table 4.2 shows the URL options recognized by the `message` servlet:

Table 4.2. URL Options Recognized by the Message Servlet

URL Option | Description
--- | ---
`type` | Can be either `queue` or `topic`.
`timeout` | When consuming a message from a queue, specifies the length of time (in units of milliseconds) the client is prepared to wait.

Three HTTP operations—`GET`, `POST`, and `DELETE`—are recognized by the `message` servlet. The semantics of these operations are described briefly in Table 4.3 .

Table 4.3. Message Servlet RESTful HTTP Operations

Operation | Description
--- | ---
`GET` | Consume a single message from the destination (queue or topic) specified by the URL.
`POST` | Send a single message to the destination (queue or topic) specified by the URL.
`DELETE` | Consume a single message from the destination (queue or topic) specified by the URL. This operation has the same effect as `GET`.

For details of the form properties recognized by the `message` servlet (for `POST`ing a message), see Example of posting a message .

### queueBrowse servlet

The RESTful service implemented by the `queueBrowse` servlet enables you to monitor the contents and status of any queue or topic in the Web console. Effectively, the `queueBrowse` servlet is a simple management tool.

To interact with the FUSE `queueBrowse` servlet, construct a URL of the following form:

    http://Host:Port/WebContext/queueBrowse/DestinationPath?Opt1=Val1&Opt2=Val2...

The `queueBrowse` URL has a similar structure to the `message` URL (see message servlet ), except that the `queueBrowse` URL is built from `WebContext``/queueBrowse` instead of `WebContext``/message`.

For example, the following URL can be used to browse the `FOO.BAR` queue, where the Web console has the default configuration:

    http://localhost:8161/demo/queueBrowse/FOO/BAR

Table 4.4 shows the URL options recognized by the `queueBrowse` servlet:

Table 4.4. URL Options Recognized by the QueueBrowse Servlet

URL Option | Description
--- | ---
`view` | Specifies the format for viewing the queue/topic. The following views are supported: `simple`—(default) displays a compact summary of the queue in XML format, where each message is shown as a `message` element with ID. `xml`—displays a detailed summary of the queue in XML format, where each message is shown in full. `rss`—displays a compact summary of the queue in the form of an RSS 1.0, 2.0 or Atom 0.3 feed. You can configure the type of feed using `feedType`.
`feedType` | In combination with the setting, `view=rss`, you can use this option to specify one of the following feeds: `rss_1.0` `rss_2.0` `atom_0.3`
`contentType` | Override the MIME content type of the view.
`maxMessages` | The maximum number of messages to render.

### Example of posting a message

Example 4.2 shows an example of the Web form used to send a message to the `FOO.BAR` queue in the Web console, as demonstrated in Send a message .

Example 4.2. Web Form for Sending a Message to a Queue or Topic

    <html>
    <head>
      <title>Send a JMS Message</title>
      <link rel="stylesheet" href="style.css" type="text/css">
    </head>
    <body>
    <h1>Send a JMS Message</h1>
    <form action="message/FOO/BAR" method="post">
      <p>
        <label for="destination">Destination name</label>
        <input type="text" name="destination"/>
      </p>
      <p>
        <label for="type">Destination Type: </label>
        <select name="type">
          <option selected value="queue">Queue</option>
          <option type" value="topic">Topic</option>
       </select>
      </p>
      <p>
        <textarea name="body" rows="30" cols="80">
    Enter some text here for the message body...
        </textarea>
      </p>
      <p>
        <input type="submit" value="Send"/>
        <input type="reset"/>
      </p>
    </form>
    </body>
    </html>

Table 4.5 describes the form properties that are recognized by the message servlet.

Table 4.5. Form Properties Recognized by Message Servlet

Form Property | Description
--- | ---
Form action | The `action` attribute of the `<form>` tag has the format, `message/``DestinationPath`, where `DestinationPath` is the compound name of the queue or topic, using forward slash, `/`, as the delimiter (for example, `FOO/BAR`).
`destination` | The compound name of the destination queue or topic, using a period, `.`, as the delimiter (for example, `FOO.BAR`). If this property is specified in the form, it overrides the value of the `DestinationPath` in the form action.
`type` | Destination type, equals `queue` or `topic`.
`body` | Message body.

### Example of getting a message

To consume a message from a topic or queue, send a HTTP GET operation (for example, by following a hypertext link) using the URL format described in message servlet . For example, to consume a message from the `FOO.BAR` queue, navigate to the following URL:

    http://localhost:8161/demo/message/FOO/BAR?timeout=10000&type=queue

### Examples of browsing a queue

To browse a queue using the `queueBrowse` servlet, simply navigate to an URL of the appropriate form, as described in queueBrowse servlet .

For example, to browse the `FOO.BAR` queue in XML format:

    http://localhost:8161/demo/queueBrowse/FOO/BAR?view=xml

To browse the `FOO.BAR` queue as an Atom 1.0 feed:

    http://localhost:8161/demo/queueBrowse/FOO/BAR?view=rss&feedType=atom_1.0

To browse the `FOO.BAR` queue as an RSS 1.0 feed:

    http://localhost:8161/demo/queueBrowse/FOO/BAR?view=rss&feedType=rss_1.0