Request Response API (R2)

Introduction

R2 is the request / response API underlying Rest.li. It includes abstractions for REST requests and responses, filter chains for customized processing, and transport abstraction. It is designed so that it can be easily customized for non-open source use cases.

R2 can be used independently, with D2 (our Dynamic Discovery system), or with both D2 and Rest.li.

Contents

Layers

The following diagram shows the layers involved in the R2 system. Each layer will be described in detail below.

Requests and Responses

In this section, we describe messages in the R2 system. The message hierarchy has ben designed to make it possible to add and work with broader message abstractions when appropriate. Originally, REST was the basic type of message in R2, but with the addition of R2 Streaming, STREAM became the most basic type of messages in R2, with REST built on top of STREAM. Because REST is the most common use case, we will stick to describing the REST model here, and leave STREAM as a separate doc.

Messages have a few properties that are worth describing here:

• They are immutable. It is not possible to change a message after it has been created. It is, however, possible to copy a message and make changes using builders, which will be described later.
• They are thread-safe due to immutability.
• New messages are created using builders.
• Existing messages can be copied and modified using builders.

Messages

"RestMessage" is the root of the message hierarchy. All messages in R2 contain an "entity" (which may be empty), and corresponds to the request or response data. For REST, the R2 entity is equivalent to a REST entity. For Streaming, because of the nature of streaming, the R2 entity is replaced by an EntityStream. R2 Streaming will be discussed more fully in a separate doc.

RestMessage has the following interface:

public interface RestMessage
{
  /**
   * Returns the entity for this message.
   *
   * @return the entity for this message
   */
  ByteString getEntity();
 
  /**
   * Returns a {@link RestMessageBuilder}, which provides a means of constructing a new message using
   * this message as a starting point. Changes made with the builder are not reflected by this
   * message instance.
   *
   * @return a builder for this message
   */
  RestMessageBuilder extends RestMessageBuilder>> builder();
}