Appendix E. Mapping REST, HTTP, and the Restlet API
This appendix is meant as a reference guide for the developer of Restlet applications. The first section lists key classes, properties, and constants used by the Restlet API and explains how they map to REST concepts, HTTP concepts, and headers.
Then we list all client and server connectors as well as the automatic representation converters available in Restlet Framework version 2.1. And we discuss the supported security challenge schemes and the authorities specific to the RIAP and CLAP pseudoprotocols.
E.1. Mapping REST concepts to Restlet classes
Table E.1 lists the main concepts of the REST architecture style and indicates the classes or interfaces of the Restlet API that materialize them.
Table E.1. Mapping REST concepts to Restlet classes
E.2. Mapping HTTP concepts to Restlet classes
Table E.2 describes the mapping between HTTP concepts and Restlet classes or interfaces.
Table E.2. Mapping HTTP concepts to Restlet classes
|
HTTP concept |
Restlet class or interface |
Definition from dissertation |
|---|---|---|
| Message | org.restlet.Message | Generic message exchanged between components, either a request or a response. |
| Request | org.restlet.Request | Generic request sent by client connectors. It’s received by server connectors and processed by Restlet. Requests are uniform across all types of connectors, protocols, and components. |
| Response | org.restlet.Response | Generic response sent by server connectors and received by client connectors. Responses are uniform across all types of connectors, protocols, and components. |
| Variant | org.restlet.representation.Variant | Descriptor for available representations of a resource. It contains all the important metadata about a representation but isn’t able to serve the representation’s content itself. |
E.3. Mapping HTTP headers to Restlet properties
The HTTP protocol is the main source of inspiration for the Restlet API, which was designed as a high-level abstraction of the HTTP protocol. On the other hand, many developers refer to HTTP headers and need a tool to help them map the Restlet API properties to those HTTP headers. Providing that tool is the aim of table E.3.
Table E.3. Mapping HTTP headers to Restlet properties
|
Header |
Restlet property name |
Restlet property class |
Description |
|---|---|---|---|
| Accept | request.clientInfo.acceptedMedia-Types | List<org.restlet.data.Preference <MediaType>> | The list of media types accepted by the client. |
| Accept-Charset | request.clientInfo.acceptedCharacterSets | List<org.restlet.data.Preference<CharacterSet>> | The list of character sets accepted by the client. |
| Accept-Encoding | request.clientInfo.acceptedEncodings | List<org.restlet.data.Preference <Encoding>> | The list of encodings accepted by the client. |
| Accept-Language | request.clientInfo.acceptedLanguages | List<org.restlet.data.Preference <Language>> | The list of languages accepted by the client. |
| Accept-Ranges | response.serverInfo.acceptingRanges | boolean | Allows the server to indicate its support for range requests. |
| Age | response.age | int | The estimated amount of time since the response was generated or revalidated by the origin server. |
| Allow | response.allowedMethods | Set<org.restlet.data.Method> | Indicates the set of allowed methods. Can be retrieved with an OPTIONS call. |
| Authentication-Info | response.authenticationInfo | org.restlet.data.AuthenticationInfo | Authentication information sent by an origin server to a client after a successful authentication attempt. |
| Authorization | request.challengeResponse | org.restlet.data.ChallengeResponse | Credentials that contain the authentication information of the user agent for the realm of the resource being requested. |
| Cache-Control | message.cacheDirectives | List<org.restlet.data.CacheDirective> | List of directives that must be obeyed by all caching mechanisms along the request/ response chain. |
| Content-Disposition | message.entity .disposition | org.restlet.data .Disposition | Means for the origin server to suggest a default filename if the user requests that the content be saved to a file. |
| Content-Encoding | message.entity.encodings | List<org.restlet.data.Encoding> | Indicates what additional content encodings have been applied to the entity-body. |
| Content-Language | message.entity.languages | List<org.restlet.data.Language> | Describes the natural language(s) of the intended audience for the enclosed entity. |
| Content-Length | message.entity .size | long | The size of the entity-body, in decimal number of OCTETs. |
| Content-Location | message.entity.locationRef | org.restlet.data.Reference | Indicates the resource location for the entity enclosed in the message. |
| Content-MD5 | message.entity.digest | org.restlet.data.Digest | Value and algorithm name of the digest associated with a representation. |
| Content-Range | message.entity.range | org.restlet.data.Range | Indicates where in the full entity-body the partial body should be applied. |
| Content-Type | message.entity.mediaType and characterSet | org.restlet.data.MediaType + CharacterSet | Indicates the media type of the entity-body. |
| Cookie | request.cookies | Series<org.restlet.data.Cookie> | List of one or more cookies sent by the client to the server. |
| Date | message.date | Date | The date and time at which the message originated. |
| ETag | message.entity.tag | org.restlet.data.Tag | The current value of the entity tag for the requested variant. |
| Expect | request.clientInfo.expectations | List<org.restlet.data.Expectation> | Indicates that particular server behaviors are required by the client. |
| Expires | message.entity.expirationDate | Date | The date/time after which the response is considered stale. |
| From | request.clientInfo.from | String | The email address of the human user controlling the user agent. |
| Host | request.hostRef | Reference | Specifies the internet host and port number of the resource being requested. |
| If-Match | request.conditions.match | List<org.restlet.data.Tag> | Used with a method to make it conditional. |
| If-Modified-Since | request.conditions.modifiedSince | Date | Used with a method to make it conditional. |
| If-None-Match | request.conditions.noneMatch | List<org.restlet.data.Tag> | Used with a method to make it conditional. |
| If-Range | request.conditions.rangeTag and rangeDate | org.restlet.data.Tag + Date | Used to conditionally return a part or the entire resource representation. |
| If-Unmodified-Since | request.conditions.unmodifiedSince | Date | Used with a method to make it conditional. |
| Last-Modified | message.entity.modificationDate | Date | Indicates the date and time at which the origin server believes the variant was last modified. |
| Location | response.locationRef | org.restlet.data.Reference | Used to redirect the recipient to a location other than the Request-URI for completion of the request or identification of a new resource. |
| Max-Forwards | request.maxForwards | int | Maximum number of proxies or gateways that can forward the request to the next inbound server. |
| Proxy-Authenticate | response.proxyChallenge-Requests | List<org.restlet.data.ChallengeRequest> | Indicates the authentication scheme(s) and parameters applicable to the proxy. |
| Proxy-Authorization | request.proxyChallenge-Response | org.restlet.data.ChallengeResponse | Credentials that contain the authentication information of the user agent for the proxy. |
| Range | request.ranges | List<org.restlet.data.Range> | List of one or more ranges to return from the entity. |
| Referer | request.refererRef | Reference | The address (URI) of the resource from which the Request-URI was obtained. |
| Retry-After | response.retryAfter | Date | Indicates how long the service is expected to be unavailable to the requesting client. |
| Server | response.serverInfo.agent | String | Information about the software used by the origin server to handle the request. |
| Set-Cookie | response.cookieSettings | Series<org.restlet.data.CookieSetting> | List of one or more cookies sent by the server to the client. |
| Set-Cookie2 | response.cookieSettings | Series<org.restlet.data.CookieSetting> | List of one or more cookies sent by the server to the client. |
| User-Agent | request.clientInfo.agent | String | Information about the user agent originating the request. |
| Vary | response.dimensions | Set<org.restlet.data.Dimension> | Indicates the set of request-header fields that fully determines, while the response is fresh, whether a cache is permitted to use the response to reply to a subsequent request without revalidation. |
| Via | message.recipientsInfo | List<org.restlet.data.RecipientInfo> | Used by gateways and proxies to indicate the intermediate protocols and recipients between the user agent and the server on requests, and between the origin server and the client on responses. |
| Warning | message.warnings | List<org.restlet.data.Warning> | Additional warning information. |
| WWW-Authenticate | response.challengeRequests | List<org.restlet.data.ChallengeRequest> | Indicates the authentication scheme(s) and parameters applicable to the Request-URI. |
| X-Forwarded-For | request.clientInfo.forwarded-Addresses | List<String> | The list of client IP addresses, including intermediary proxies. |
| X-HTTP-Method-Override | tunnelService.methodHeader | org.restlet.data.Method | Overrides the HTTP method for limited clients such as browsers. |
By convention, the list of property names refers to Restlet classes such as Request, Response, or Message. The “Restlet property name” column contains values such as request.clientInfo.acceptedMediaTypes and response.age, referring to Java properties of the message classes. Those properties are accessible using the getter and setter methods, such as Request.getClientInfo().getAcceptedMediaTypes() and Response.getAge().
E.4. Available connectors
As mentioned in chapter 1, connectors are an essential part of the REST architectural style. They enable communication between components by implementing a particular network protocol.
Because of the distinction between client and server components, this section contains two tables: one for the server connectors and one for client connectors as available in Restlet Framework version 2.1. Table E.4 lists the server connectors ordered by protocol name. Those connectors are available either in the core Restlet module (org.restlet) or in extension modules (org.restlet.ext.<moduleName>).
Table E.4. Server connectors
|
Protocol |
Module |
|---|---|
| AJP | jetty |
| HTTP | core, jetty, simple |
| HTTPS | ssl, jetty, simple |
| RIAP | core |
| SIP | sip |
| SIPS | sip |
Table E.5 lists all the client connectors available.
Table E.5. Client connectors
E.5. Available converters
As discussed elsewhere in the book, the ConverterService plays a key role in the content negotiation and automatic conversion feature between beans and raw representations.
Table E.6 lists the modules (either the core module or the extensions) that provide automatic serialization from representation beans to raw representations, including the media types and classes or interfaces supported.
Table E.6. Converters that provide automatic serialization
Note that the order of the converters in your classpath might matter and that each converter can express different scores for each media type or class, depending on their affinity with them.
Table E.7 lists the modules (either the core module or the extensions) that provide automatic deserialization of raw representations into representation beans, including the media types and classes or interfaces supported.
Table E.7. Converters that provides automatic deserialization
E.6. Supported security challenge schemes
Table E.8 lists all the security schemes supported by the Restlet Framework and the corresponding extensions (see also chapter 5). It also indicates whether the client and/or server sides of the security scheme are implemented.
Table E.8. Challenge schemes and their implementation
E.7. Scheme authorities of RIAP and CLAP pseudoprotocols
We’ve introduced the RIAP and CLAP pseudoprotocols in order to complete the vision of a unified way to access resources, even within a Restlet component, and not only from the outside using a network protocol.
Much as HTTP lets you access resources on the Web, RIAP lets you access resources defined in your own Restlet applications and components, whereas CLAP lets you access resources available via Java class loaders.
Such resources are designated as local resources. A special Reference subclass called org.restlet.data.LocalReference facilitates the creation of such references to local resources with several methods, such as createClapReference() and create-RiapReference().
Table E.9 lists all important constants related to those pseudoprotocols and supported by the org.restlet.data.LocalReference class. The table should help you understand which kind of resource can be targeted.