Learn Restlet Framework


Mapping HTTP headers

Introduction

The Restlet API offers a higher level view of the HTTP protocol. It tries to abstract and present in a clean object model, the application-level semantics of HTTP. As a side feature, it is possible to map other protocols to the same semantics, such as FILE, FTP, SMTP, etc.

However, developers often know lower-level details of HTTP or need to understand them for debugging purpose. This is the reason for this document, explaining the mapping between the HTTP semantics and the Restlet API.

Note that the headers that are not supported yet can still be overridden via the "org.restlet.http.headers" attribute of the request or the response. A warning message is  logged : "Addition of the standard header "XXX" is discouraged. Future versions of the Restlet API will directly support it".

See details in the Javadocs of the Message.getAttributes() method.

From HTTP headers to Restlet API

HTTP header Restlet property name Restlet property class Description
Accept request.clientInfo.acceptedMediaTypes org.restlet.data.Preference<MediaType> The list of media-types accepted by the client. 
Accept-Charset request.clientInfo.acceptedCharacterSets org.restlet.data.Preference<CharacterSet> The list of character sets accepted by the client.
Accept-Encoding request.clientInfo.acceptedEncodings org.restlet.data.Preference<Encoding> The list of encodings accepted by the client.
Accept-Language request.clientInfo.acceptedLanguages org.restlet.data.Preference<Language> The list of languages accepted by the client.
Accept-Ranges response.serverInfo.acceptRanges 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> For "Handler" subclasses (such as Resource), a dynamic search is made that looks for the "allow*" methods declared on the class and that return "True".
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.
Connection [HTTP connectors] - Set to "close" according to the server or client connector property (serverKeepAlive or clientKeepAlive, keepAlive). The internal client and server connectors introduce the "persistingConnections" parameter.
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 is saved to a file.
Content-Encoding message.entity.encodings List<org.restlet.data.Encoding> Indicates what additional content codings 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 to 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 was 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.
Pragma [Deprecated] - Support for misc headers planned for later
Proxy-Authenticate response.proxyChallengeRequests List<org.restlet.data.ChallengeRequest> Indicates the authentication scheme(s) and parameters applicable to the proxy.
Proxy-Authorization request.proxyChallengeResponse 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 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.
TE - - Support for misc headers planned for later
Trailer - - Support for misc headers planned for later
Transfer-Encoding [HTTP connectors] - Valuated to "chunked" if the entity is not null and its size is unknown (Representation.UNKNOWN_SIZE).
Upgrade - - Support for misc headers planned for later
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 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> The additional warnings 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.forwardedAddresses List<String> The list of client IP addresses, including intermediary proxies.
X-HTTP-Method-Override [Tunnel service] org.restlet.data.Method Allows to override the HTTP method specified in the request (typically by a limited client such as a browser) by one specified in this special extension header.

Appendix

Registry of headers maintained by IANA. Regsitry of HTTP status codes maintained by IANA.