OverviewBy default the OpenPTK Server obtains the MimeType, for requests and responses, information from the standard HTTP Header variables: There are some clients that either can not set HTTP Header variable or prefer to use a modified URI to indicate the payload encoding mimeType. Typical inbound payloads (via POST and PUT) use either XML or JSON. Typical outbound payloads (via GET) use XML, JSON, PLAIN, HTML. ImplementationAs of release 2.1 of Project OpenPTK, it supports the use of URI options to indicate the MimeType. There are two options that are supported: - Query Parameter
- URI Suffix
A new ServletFilter (MimeTypeHeaderFilter) has been created to handle the processing of the modified URI. By default, this filter is disabled. The ServletFilter will add Header variables to the HTTP Request. If a query parameter is used, it will be removed. If a suffix was used, it will be removed. The ServletFilter will be configurable via the web.xml file. It supports the following modes:
Mode | Description | disabled | The ServletFilter is not enabled, it will be skipped. This is the default. | parameter | The ServletFilter will look for a valid query parameter with the name format. If it is found, it will use the value to set the Accept and/or Content-Type HTTP header variable. Here are the valid query parameter values:
| suffix | The ServletFilter will look for a suffix appended to the end of the URI. If a valid suffix is found, the suffix value will be used to set the Accept and/or Content-Type HTTP header variable. Here are the valid suffixes:
| both | The ServletFilter will look for the query parameter format and for a suffix. The ServletFilter checks for a suffix first. If a suffix is found, it's value will be used to set the mimeType. The suffix ServletFilter then checks for the format query parameter. If the query parameter is found, it's value is used to set the mimeType. If both are found, the query parameter value will override the suffix value. |
Here is the logic for which mechanism will be used. - If nothing is set, an internal default is used
- If only Header, the header is used
- If a Header and a Suffix, the suffix is used
- If a Header and a Param, the param is used
- If a Suffix and a Param, the param is used
- If a Header and Suffix and Param, the param is used
The "X" indicates a valid mime-type
Header | Suffix | Param | Actually Used | | | | Default | X | | | Header | | X | | Suffix | X | X | | Suffix | | | X | Param | X | | X | Param | | X | X | Param | X | X | X | Param |
LimitationsThe top level REST paths do not support the use of a suffix to specify the mime-type. The mime-type can still be set with the Header variable or with the query parameter "format". The following URIs do not support the suffix mechanism.
clients | .../resources/clients.json | contexts | .../resources/contexts.xml
| engine | .../resources/engine.json | sessioninfo | .../resources/sessioninfo.xml |
Notice: this is only the top level. Sub path element do work with the suffix mechanism.
EnablingEdit the Server's WEB-INF/web.xml and change the <init-param> value to either parameter, suffix or both. It is recommended that either parameter or suffix be used for potential performance reasons.
<filter>
<description>processes HTTP query parameters</description>
<filter-name>MimeTypeHeader</filter-name>
<filter-class>org.openptk.servlet.filters.MimeTypeHeaderFilter</filter-class>
<init-param>
<param-name>mode</param-name>
<param-value> disabled </param-value> <!-- disabled, parameter, suffix, both -->
</init-param>
<init-param>
<param-name>debug</param-name>
<param-value>2</param-value> <!-- 0, 1, 2, 3, 4 -->
</init-param>
</filter>
Usage
Here are the support suffix values: The following URIs support the use of a suffix
Syntax | Example | contexts/{contextid}[suffix] | contexts/Employees-Embed-JDBC.json | contexts/{contextid}/subjects[suffix] | contexts/Employees-Embed-JDBC/subjects.xml | contexts/{contextid}/subjects/{subjectid}[suffix] | contexts/Employees-Embed-JDBC/subjects/ja1324.html |
The following URL is submitted ...
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/ja1324.json
Notice the following changes: - Before
- The path had '.json' as a suffix
- The Header variable 'accept' is '*/*'
- After
- The path no longer has the '.json' suffix
- The Header variable 'accept' is 'application/json'
Here are the support suffix values: - ?format=xml
- ?format=json
- ?format=html
- ?format=plain
The following URIs support the use of a Query Parameter
Syntax | Example | contexts/{contextid}\?format=[format] | contexts/Employees-Embed-JDBC\?format=xml | contexts/{contextid}/subjects\?format=[format] | contexts/Employees-Embed-JDBC/subjects\?format=xml | contexts/{contextid}/subjects/{subjectid}\?format=[format] | contexts/Employees-Embed-JDBC/subjects/ja1324\?format=html |
The following URL is submitted ...
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/ja1324\?format=json
|
|