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 |
|---|---|---|---|
| Access-Control-Allow-Credentials | response.accessControlAllowCredentials | Boolean | Indicates whether the response to request can be exposed when the omit credentials flag is unset. When part of the response to a preflight request it indicates that the actual request can include user credentials. |
| Access-Control-Allow-Headers | response.accessControlAllowHeaders | Set<String> | Indicates, as part of the response to a preflight request, which header field names can be used during the actual request. |
| Access-Control-Allow-Methods | response.accessControlAllowMethods | Set<org.restlet.data.Method> | Indicates, as part of the response to a preflight request, which methods can be used during the actual request. |
| Access-Control-Allow-Origin | response.accessControlAllowOrigin | String | Indicates whether a resource can be shared based by returning the value of the Origin request header, “*”, or “null” in the response. |
| Access-Control-Expose-Headers | response.accessControlExposeHeaders | Set<String> | Indicates which headers are safe to expose to the API of a CORS API specification. |
| Access-Control-Request-Headers | request.accessControlRequestHeaders | Set<String> | Indicates which headers will be used in the actual request as part of the preflight request. |
| Access-Control-Request-Method | request.accessControlRequestMethod | org.restlet.data.Method | Indicates which method will be used in the actual request as part of the preflight request. |
| 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-Patch | request.clientInfo.acceptedPatches | org.restlet.data.Preference<MediaType> | Specifies the patch document formats accepted by the server. |
| 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. Registry of HTTP status codes maintained by IANA.