Projects‎ > ‎

RESTful Header variable mime-type alternatives

Overview

This project will address the situation where a client either can not, or prefers to not use Header variables for declaring the a Request's or Response's mime-type.  This feature would provide an alternative to using HTTP Header variables. This project will allow the client to declare the mime-type by either using a URI "suffix" or by setting a Query Parameter.

This project will also address an issue of an un-declared mime-type.  The wildcard "*/*" was used when a mime-type was not set.  This project will implement a feature where the default mime-type will be "text/plain".  This is really only an issue for those operations that return data (search and read) which use GET.

Issue:

JIRA: http://java.net/jira/browse/OPENPTK-300

URI Suffix Examples

GET

The HTTP Response data would be formatted using the specific suffix.
curl ... /contexts/devel/subjects/ja1324.json
curl ... /contexts/devel/subjects/ja1324.xml
curl ... /contexts/devel/subjects/ja1324.html
curl ... /contexts/devel/subjects/ja1324.plain


POST

The HTTP Request data (payload) would be formatted with the specific suffix.
curl -X POST ... /contexts/embedded/subjects.json
curl -X POST ... /contexts/embedded/subjects.xml


PUT

The HTTP Request data (payload) would be formatted with the specific suffix.
curl -X PUT ... /contexts/devel/subjects/ja1324.json
curl -X PUT ... /contexts/devel/subjects/ja1324.xml

Query Parameter Examples

GET

The HTTP Response data would be formatted using the specific suffix.
curl ... /contexts/devel/subjects/ja1324\?fomat=json
curl ... /contexts/devel/subjects/ja1324\?format=xml
curl ... /contexts/devel/subjects/ja1324\?fomat=html
curl ... /contexts/devel/subjects/ja1324\?format=plain

POST

The HTTP Request data (payload) would be formatted with the specific suffix.
curl -X POST ... /contexts/embedded/subjects\?format=json
curl -X POST ... /contexts/embedded/subjects\?format=xml

PUT

The HTTP Request data (payload) would be formatted with the specific suffix.
curl -X PUT ... /contexts/devel/subjects/ja1324\?format=json
curl -X PUT ... /contexts/devel/subjects/ja1324\?format=xml

Implementation

A ServletFilter will be created to check the URI for the format query parameter.  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
 disabledThe ServletFilter is not enabled, it will be skipped.  This is the  default.
 parameterThe 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
 suffixThe 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
 bothThe 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

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

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


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

Classes

  • MimeTypeHeaderFilter
    • Extends BaseFilter
    • Leverages web.xml init param for configuration: 
      • mode: disabled, parameter, suffix, both
      • debug: 0, 1, 2, 3, 4
    • Uses the MimeTypeHeaderRequestWrapper
  • MimeTypeHeaderRequestWrapper
    • Checks for the query parameter: format
    • Overloads methods
      • String getHeader(String name)
      • Enumeration<String> getHeaders(String name)
      • Enumeration<String> getHeaderNames()
      • String getContentType()
      • String getQueryString()
      • String getParameter(String name)
      • Map<String, String[]> getParameterMap()
      • Enumeration getParameterNames()
      • String[] getParameterValues(String name)
      • String getPathInfo()
      • String getRequestURI()
      • StringBuffer getRequestURL()
      • ServletInputStream getInputStream() throws IOException
      • BufferedReader getReader() throws IOException
Configuration

web.xml

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

Test Cases

Login

curl -c cookies.txt http://localhost:8080/openptk-server/login?user=openptkconfig\&password=password\&clientid=identitycentral


Query Parameter

Create

curl -X POST -v -b cookies.txt -d '{"subject" : { "attributes" : { "lastname" : "Bauer", "title" : "Agent", "firstname" : "Jack", "telephone" : "123-456-7890", "email" : "jack@ctu.gov" }}}' http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects\?format=json

Read

curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/jbauer\?format=json
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/jbauer\?format=xml
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/jbauer\?format=plain
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/jbauer\?format=html

Update

curl -X PUT -v -b cookies.txt -d '{ "subject" : { "attributes" : { "title" : "Super Agent" } } }' http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/jbauer\?format=json

Search

curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects\?format=json\&search=jack
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects\?format=xml\&search=jack
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects\?format=plain\&search=jack
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects\?format=html\&search=jack

Suffix

Create

curl -X POST -v -b cookies.txt -d '{"subject" : { "attributes" : { "lastname" : "Cauer", "title" : "Agent", "firstname" : "Jack", "telephone" : "123-456-7890", "email" : "jack@ctu.gov" }}}' http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects.json

Read

curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/jcauer.json
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/jcauer.xml
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/jcauer.plain
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/jcauer.html

Update

curl -X PUT -v -b cookies.txt -d '{ "subject" : { "attributes" : { "title" : "Super Agent" } } }' http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/jcauer.json

Search

curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects.json\?search=jack
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects.xml\?search=jack
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects.plain\?search=jack
curl -X GET -v -b cookies.txt http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects.html\?search=jack