Mapping HTTP semantics

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, explain 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.

Mapping headers

HTTP header	Restlet property	Description
Accept	request.clientInfo.acceptedMediaTypes	The list of media-types accepted by the client.
Accept-Charset	request.clientInfo.acceptedCharacterSets	The list of character sets accepted by the client.
Accept-Encoding	request.clientInfo.acceptedEncodings	The list of encodings accepted by the client.
Accept-Language	request.clientInfo.acceptedLanguages	The list of languages accepted by the client.
Accept-Ranges	[connector level]	Allows the server to indicate its support for range requests
Age	-	Support for caching planned for Restlet 1.2
Allow	response.allowedMethods	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	-	Non standard HTTP header.
Authorization	request.challengeResponse	Credentials that contain the authentication information of the user agent for the realm of the resource being requested.
Cache-Control	-	Support for caching planned for Restlet 1.2
Connection	[connector level]	Set to "close" according to the server or client connector property (serverKeepAlive or clientKeepAlive).
Content-Disposition	message.entity.downloadName	If the download name is not null, the header value is "attachment; filename=<entity.downloadName>".
Content-Encoding	entity.encodings	Indicates what additional content codings have been applied to the entity-body.
Content-Language	entity.languages	Describes the natural language(s) of the intended audience for the enclosed entity.
Content-Length	entity.size	The size of the entity-body, in decimal number of OCTETs.
Content-Location	entity.identifier	Indicates the resource location for the entity enclosed in the message.
Content-MD5	representation.digest	Value and algorithm name of the digest associated to a representation.
Content-Range	entity.range	Indicates where in the full entity-body the partial body should be applied
Content-Type	entity.mediaType and entity.characterSet	Indicates the media type of the entity-body.
Cookie	request.cookies	List of one or more cookies sent by the client to the server.
Date	current date	The date and time at which the message was originated.
ETag	entity.tag	The current value of the entity tag for the requested variant.
Expect	-	Support for expect header planned for Restlet 1.2
Expires	entity.expirationDate	The date/time after which the response is considered stale.
From	-	Support for misc headers planned for later
Host	request.resourceRef (domain and port)	Specifies the Internet host and port number of the resource being requested.
If-Match	request.conditions.match	Used with a method to make it conditional.
If-Modified-Since	request.conditions.modifiedSince	Used with a method to make it conditional.
If-None-Match	request.conditions.noneMatch	Used with a method to make it conditional.
If-Range	-	Support planned for Restlet 1.2
If-Unmodified-Since	request.conditions.unmodifiedSince	Used with a method to make it conditional.
Last-Modified	entity.modificationDate	Indicates the date and time at which the origin server believes the variant was last modified.
Location	response.locationRef	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	-	Support for proxies planned for later
Pragma	-	Support for caching planned for Restlet 1.2
Proxy-Authenticate	response.proxyChallengeRequests	Indicates the authentication scheme(s) and parameters applicable to the proxy.
Proxy-Authorization	request.proxyChallengeResponse	Credentials that contain the authentication information of the user agent for the proxy.
Range	request.ranges	List one or more ranges to return from the entity
Referer	request.refererRef	The address (URI) of the resource from which the Request-URI was obtained.
Retry-After	-	Support for misc headers planned for later
Server	response.serverInfo.agent	Information about the software used by the origin server to handle the request.
Set-Cookie	response.cookieSettings	List of one or more cookies sent by the server to the client.
Set-Cookie2	response.cookieSettings	List of one or more cookies sent by the server to the client.
TE	-	Not supported yet
Trailer	-	Support for misc headers planned for later
Transfer-Encoding	entity.size	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	Information about the user agent originating the request.
Vary	response.dimensions	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	-	Support for proxies planned for later
Warning	-	Support for caching planned for Restlet 1.2
WWW-Authenticate	response.challengeRequests	Indicates the authentication scheme(s) and parameters applicable to the Request-URI.
X-Forwarded-For	request.clientInfo.addresses	The list of client IP addresses, including intermediary proxies.
X-HTTP-Method-Override	[tunnel service]	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.

Comments (0)