[OASIS Issue Tracker] Commented: (CAMP-13) Media Type "type" argument not compatible with Python request parsers

[OASIS Issues Tracker <workgroup_mailer@lists.oasis-open.org>]

    [ http://tools.oasis-open.org/issues/browse/CAMP-13?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=31634#action_31634 ] 

Adrian Otto commented on CAMP-13:
---------------------------------

1. Introduction

CAMP specification uses JSON as the serialization format for all CAMP resource representations1. The media-type used for the resource representations is of the form application/vnd.org.example.PaaS+json, with the intention that the TC would register a new media-type with IANA of the form 'application/<camp>+json (where <camp> is a short string acceptable to the TC and IANA). To differentiate various resource types such as 'Assembly', 'AssemblyTemplate', etc, the media type uses the 'type' parameter. The value of the 'type' parameter is the type of the resource that is being represented. For example, the media-type of the Assembly resource is:
application/vnd.org.example.PaaS+json; type=Assembly

2. Issues

There are several issues with such a media-type:

1. The type parameter is being used to avoid registering large number of media-types with IANA.
This circumvents the intent behind having a central IANA registry.
2. IANA is not going to manage the space defined by the type parameter. We'll have to figure out
how to manage this space, especially when it comes to extensions.
3. As a consequence of (1) above, some consider the current solution a "hack".
4. Most (all?) public REST APIs that use JSON as the serialization format avoid defining their
own media-type and just use application/json.
5. Python libraries when processing an HTTP message strip all parameters (except for a few well
known ones like the 'q' parameter) off HTTP headers. Applications written in Python that use
standard libraries cannot use the information available in the 'type' parameter.
6. Several IETF specifications (for example, RFC 5988) do not use a parametrized media-type. All
information provided in the 'type' parameter is therefore lost when used in such specifications.

3. Solution Space

This issue was discussed extensively in the collaboration that created CAMP version 1.0. There were several reasons for using the current solution:

1. Creating a media-type per CAMP resource type is just not feasible. A very large number of media-type specs would have to be written and registered with IANA. Furthermore, everyone creating an extension would have to keep inventing new media-types for every new resource type.
2. JAX-RS dispatching can be done only based on URL or HTTP headers (including the Content- Type header and its parameters).
3. application/json media type does not define any parameters, if parametrized media-type is required then a new media-type has to be created.
1 Other formats are allowed, though not defined in the specification. Providers are required to support JSON format.

There are four possible approaches:

1. Status quo
2. Use application/json
3. Register one media type (application/camp+json) with no parameters
4. Register a media type for every new CAMP resource type.

#4 is just not practical. It is also not clear why we would do such a thing. A comparison can be made to defining a media type for every XML schema global element that is sent as the root element in an HTTP entity-body. No one ever does that and for a good reason.
#3 does not provide much advantage over #2. The CAMP client communicating to a CAMP provider would/should know that it is using CAMP protocol and therefore expect CAMP resources. Similarly, a CAMP provider, due to the fact that it implements the spec expects all messages to be CAMP message (or some extension). What is important, when both ends are CAMP-aware, is to include information about the serialization format (json, xml, etc - as implementations are free to provide alternate serializations).
#1 and #2 seems to be the right set of alternatives. The argument in favor of #1 (in addition to what is already presented) is that for those specifications or libraries/languages that don't use or recognize content-type parameters, #1 and #2 are more or less equivalent (wrt parameters), but for languages/framworks/libraries that do not strip content-type parameters this is very useful in dispatching/binding.
OTOH, #2 keeps things loosely coupled, keep with the tradition of all the other REST-JSON APIs (and therefore won't be considered "hacky"), do not require any management of the 'type' parameter space, nor do they circumvent the intention behind IANA's type registry.

> Media Type "type" argument not compatible with Python request parsers
> ---------------------------------------------------------------------
>
>                 Key: CAMP-13
>                 URL: http://tools.oasis-open.org/issues/browse/CAMP-13
>             Project: OASIS Cloud Application Management for Platforms (CAMP) TC
>          Issue Type: Improvement
>          Components: Spec
>            Reporter: Anish Karmarkar
>
> In creating the spec there was a compromise made for how the spec should handle Media Types:
> > We register exactly one media type for all resources: application/name+format
> > The specific resource type is declared via a "type" parameter:
> > application/name+format;type=type
> > We allow different formats to be delivered, with JSON being the default (and hence required)
> > format: application/name+json;type=type
> > In case XML is delivered, it is just another format. I.e. we don't define any schemata or aid in
> > validating Format discovery should happen through a GET on the /api/formats URL but
> > implementations are free to not provide this in which case clients need to fall back to discovery
> > by trial (via the "Accept" header)
> > If alternative formats are supported, they need to be supported uniformly for all resources
> It has come to my attention that the Openstack group tried to use this technique, and could not make it work in Python. The Python request parsing libraries (they tried all the available choices apparently) did not recognize the parameter, and stripped it. They were able to handle the q= parameter, but not type=.
> Considering the popularity of Python in web service API's it would be a mistake to proceed with our current strategy of using the type= parameter unless the Python request parsing libraries are first enhanced to be able to deal with it properly, and not strip it from the request.
> It may also affect other languages/systems in a similar way.
> This issue was raised by Adrian Otto and was drupal issue 1075

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://tools.oasis-open.org/issues/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira