MimeType via URI

Release 2.x‎ > ‎Install - Reference‎ > ‎

Overview

By default the OpenPTK Server obtains the MimeType, for requests and responses, information from the standard HTTP Header variables:

Accept
Content-Type

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.

Implementation

As 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: xml json html plain
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: .xml .json .html .plain
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

Limitations

The 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.

Enabling

Edit 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> 

</init-param>

<init-param>

<param-name>debug</param-name>

<param-value>2</param-value> 

</init-param>

</filter>

Usage

URI Suffix

Here are the support suffix values:

.xml
.json
.html
.plain

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'

URI Query Parameter