Subject: [weirds] feedback on draft-designteam-weirds-using-http

From: Julian Reschke <[email-masked]>
Date: Tue, 15 May 2012 15:56:18 +0200

Hi there,

it would be great if the boilerplate did specify the discussion venue 
(this would have avoided one roundtrip to the authors :-).

That being said: see comments inline.

1.  Introduction

    ...

    This document describes the usage of HTTP for Internet registry Whois
    services running on RESTful web servers for the purposes of
    addressing the deficiencies as described above.  The goal of this
    document is to tie together the usage patterns of HTTP into a common
    profile applicable to the various types of Internet registries
    serving Whois data using RESTful styling.  By giving the various
    Internet registries a common behavior, a single client is better able
    to retreive data from Internet registries adhering to this behavior.

a) I would be very careful in using "RESTful" when your intent 
essentially is only but using HTTP properly. In particular, the document 
seems to be silent on how the client actually discovers the URI it can 
send requests to (or alternatively, in case the URIs essentially are 
hardwired, that definition is missing).

b) s/retreive/retrieve/

    The goal of this specification is to define a simple use of HTTP to
    deliver Whois information using RESTful patterns.  Where complexity
    may reside, it is the goal of this specification to place it upon the
    server and to keep the client as simple as possible.  In the
    vacubulary of computer programmers, it should be suffecient enough to

s/vacubulary/vocabulary/
s/suffecient/sufficient/

    write a client for this application in bash using commands such as
    wget or curl and other commonly available command line tools.

    This is the basic usage pattern for this protocol:

    1.  A client issues an HTTP query using GET.  As an example, a query

s/query/request/

        for the network registration 192.168.0.0 might be
        http://example.com/ip/192.168.0.0.

    2.  If the receiving server has the information for the query, it
        examines the Accept header of the query and returns a 200
        response with a response entity appropriate for the requested
        format.

    3.  If the receiving server does not have the information for the
        query but does have knowledge of where the information can be
        found, it will return a response of 301 or 303 with the Redirect
        header containing an HTTP URL pointing to the information.  The
        client is expected to re-query using that HTTP URL.

s/header/header field/

It's also not clear why it needs to be 301 or 303 here.

    ...

3.  Design Intents

    There are a few design criteria this document attempts to support.

    First, each query is meant to return either zero or one result.  With
    the maximum upper bound being set to one, the issuance of redirects
    is simplified to the known document model used by HTTP [RFC2616].

Document model?

    ...

4.  Queries

4.1.  Accept Header

    Clients SHOULD put the MIME type of the format they desire in the

a) Why is this a SHOULD? What's the impact of not doing so?

b) s/MIME type/media type/

    Accept header.  Servers SHOULD respond with an appropriate MIME type
    in the Accept header in accordance with the preference rules for the
    Accept header in HTTP [RFC2616].  However the use by clients of
    multiple MIME types in the Accept header is NOT RECOMMENDED.

It's not clear to me why you're profiling HTTP here.

    Clients may use a generic MIME type for the desired data format of
    the response, but servers MUST respond with the most appropriate MIME
    type.  In other words, a client may use "application\json" to express

s|application\json|application/json| (throughout the documemt)

    that it desires JSON or "application\weirds_blah_v1+json" to express
    that it desires WEIRDS BLAH version 1 in JSON.  The server MUST
    respond with "application\weirds_blah_v1+json".

This seems to invent a new concept of media ranges in content 
negotiation that didn't exist before. Why is this needed?

4.2.  Parameters

    To overcome issues with misbehaving HTTP [RFC2616] cache
    infrastructure, clients may use the '__weirds__cachebust' query
    parameter with a random value of their choosing.  Servers MUST ignore
    this query parameter.

    The following is an example use of this parameter to retreive the
    abuse contacts associated with the most specific IP network with the
    address 192.0.2.0:

      /ip/192.0.2.0/operator/contacts/abuse?__weirds_cachebust=xyz123

    For all others, servers SHOULD ignore unknown query parameters.

I think what you're saying is that all query parameters are ignored, right?

The whole concept of reserving a specific one is strange to say the 
least.

    ...

5.  Types of HTTP Response

   ...

5.2.  Redirects

    If a server wishes to inform a client that the answer to a given
    query can be found elsewhere, it should return either a 301 or a 303
    reponse code and an HTTP URL in the Redirect header.  The client is

s/reponse/response/

    expected to issue a subsequent query using the given URL without any
    processing of the URL.  In other words, the server is to hand back a
    complete URL and the client should not have to transform the URL to
    follow it.

HTTPbis allows relative URIs here, and so should this protocol.

    A server should use a 301 response to inform the client of a
    permanent move and a 303 repsonse otherwise.  For this application,

This makes it sound as if it should be 302, not 303. It's also not 
clears why 307 (and maybe 308) aren't mentioned here.

s/repsonse/response(

    such an example of a permentant move might be a TLD operator

s/permentant/permanent/

    informing a client the information being sought can be found with
    another TLD operator (i.e. a query for the domain bar in foo.example
    is found at http://foo.example/domain/bar).

   ...

5.4.  Malformed Queries

    If a server receives a query which it cannot understand, it SHOULD
    return a 503 response code.  Optionally, it may include additional
    information about why it does not understand the query as defined by
    Section 8.

If the problem is the request than the status code should be a 4xx.

    ...

6.2.  Naming

    JSON names SHOULD only consist of the alphabetic ASCII characters A
    through Z in both uppercase and lowercase, underscore characters, and
    SHOULD NOT begin with an underscore character or the characters
    "xml".  This restriction is a union of the Ruby programming language
    identifier syntax and the XML element name syntax and has two
    purposes.  First, client implementers using modern programming
    languages such as Ruby or Java may use libraries that automatically
    promote JSON values to first order object attributes or members (e.g.
    using the example above, the values may be referenced as
    network.handle or network.lunarNic_beforeOneSmallStep).  Second, a
    clean mapping between JSON and XML is easy to accomplish using the
    JSON representation.

I think ABNF would be good here, even if the XML prefix exclusion be 
just in prose.

Also: no digits???

    ...

7.  Use of XML

7.1.  Signaling

    Clients may signal their desire for XML using the "application\xml"
    mime type or a more application specific XML mime type.

7.2.  Naming and Structure

    Well-formed XML may be programmatically produced using the JSON
    encodings due to the JSON naming rules outlined in Section 6.2 and
    the following simple rules:

    1.  Where a JSON name is given, the corresponding XML element has the
        same name.

    2.  Where a JSON value is found, it is the content of the
        corresponding XML element.

That is not true for all JSON values (consider control characters).

    ...

8.  Common Error Response Body

    As specified in Section 5, some non-answer responses may return
    entity bodies with information that could be more descriptive.

    The basic structure of that response is a data class containing an
    error code number (corresponding to the HTTP response code) followed
    by a string named "title" followed by an array of strings named
    "description".

    This is an example of the JSON version of the common response body.

      {
        "errorCode": 418
        "title": "No More Tacos",
        "description": [
          "We ran out of shells and sauce.",
          "Come back tomorrow." ]
      }

That doesn't seem to be a good example of 
<http://tools.ietf.org/html/rfc2324#section-2.3.2> :-)

    The MIME type for the JSON structure is
    "application\weirds_common_error_v1+json" and the MIME type for the
    XML document is "application\weirds_common_error_v1+xml".

Are you going to register these with IANA?

    A client MAY simply use the HTTP response code as the server is not
    required to include error data in the response body.  However, if a
    client wishes to parse the error data, it SHOULD first check that the
    Accept header contains the appropriate MIME type.

s/Accept/Content-Type/

Best regards, Julian

---

From: Andy Newton <[email-masked]>
Date: Thu, 17 May 2012 10:50:46 -0400

Hi Julian,

Responses in-line.

On May 15, 2012, at 9:56 AM, Julian Reschke wrote:

> it would be great if the boilerplate did specify the discussion venue (this would have avoided one roundtrip to the authors :-).

noted.

> a) I would be very careful in using "RESTful" when your intent essentially is only but using HTTP properly. In particular, the document seems to be silent on how the client actually discovers the URI it can send requests to (or alternatively, in case the URIs essentially are hardwired, that definition is missing).

The purpose of talking about RESTful styling is that the group has decided to head in that direction, instead of doing something like SOAP over HTTP. Perhaps there is context missing here that can only be found in the other drafts.

As for discovery, are you talking about service discovery or something simpler like URI templates?

> It's also not clear why it needs to be 301 or 303 here.

Yes, it might be better just to suggest any of the HTTP redirects.

>   is simplified to the known document model used by HTTP [RFC2616].

Sorry, probably should be request/response model or document retrieval model.

> It's not clear to me why you're profiling HTTP here.

Because for this application, clients will probably only know one format. The need to use the complex rules for specifying multiple formats is unnecessary.

> This seems to invent a new concept of media ranges in content negotiation that didn't exist before. Why is this needed?

For signaling the version of the schema desired. Is there another method you feel is more appropriate?

> The whole concept of reserving a specific one is strange to say the least.

I don't know if it is strange, but I see your point. We simply need to state that all query unknown parameters should be ignored and the problem takes care of itself.

> HTTPbis allows relative URIs here, and so should this protocol.

Why? It is simpler for the clients if the URLs are absolute.

> This makes it sound as if it should be 302, not 303. It's also not clears why 307 (and maybe 308) aren't mentioned here.

I need to take a look at this. But I suspect more thought is needed as you have indicated.

> If the problem is the request than the status code should be a 4xx.

Yes, it should be. This is a mistake.

> I think ABNF would be good here, even if the XML prefix exclusion be just in prose.
> 
> Also: no digits???

Good point, and good catch. Digits should be allowed.

> That is not true for all JSON values (consider control characters).

Ah yes, the escaping needs to be changed from JSON to XML.

> That doesn't seem to be a good example of <http://tools.ietf.org/html/rfc2324#section-2.3.2> :-)

right. Let me fix that
{
  "errorCode": 418,
  "title": "Your beverage choice is not available",
  "description": [
    "I know coffee has more ummppphhh.",
    "But I cannot provide." ]
}

> Are you going to register these with IANA?

Yes. That is a todo.

>   Accept header contains the appropriate MIME type.

Good catch.

Thanks for the feedback.

-andy

---

From: Julian Reschke <[email-masked]>
Date: Thu, 17 May 2012 18:00:52 +0200

Hi Andy,

thanks for the feedback. Replies inline.

> As for discovery, are you talking about service discovery or something simpler like URI templates?

Aha, so you're not there yet :-)

Using URI templates sound promising.

> Because for this application, clients will probably only know one format. The need to use the complex rules for specifying multiple formats is unnecessary.

I don't follow. Servers need to process the Accept header field 
according to RFC 2616. Are you saying they can rely on it being simpler? 
In which case, this would need to be a "MUST NOT".

> For signaling the version of the schema desired. Is there another method you feel is more appropriate?

The method is probably ok, but the way it was explained was confusing: 
client specifies it wants "A", but server is allowed to return "B" (and 
label it as "B"), if it has out-of-band info that the client will 
understand it, too. Note that here "A" and "B" could be any media type 
(the label is really opaque).

> I don't know if it is strange, but I see your point. We simply need to state that all query unknown parameters should be ignored and the problem takes care of itself.

Yep.

I'd also move the discussion of cache busting into an appendix, or not 
mention it at all; it's not specific to this protocol.

> Why? It is simpler for the clients if the URLs are absolute.

Do not profile the base protocol unless there is a very very good reason.

> Ah yes, the escaping needs to be changed from JSON to XML.

There's still a set of characters that won't be usable in XML (yes, not 
even escaped).

>> That doesn't seem to be a good example of<http://tools.ietf.org/html/rfc2324#section-2.3.2>  :-)
>
> right. Let me fix that
> {
>    "errorCode": 418,

Thanks :-) Larry will be happy.

Best regards, Julian

---

From: Arturo Servin <[email-masked]>
Date: Thu, 17 May 2012 14:16:08 -0300

I think it is important to mention it. Otherwise you will end up with different approaches to solve the problem for getting fresh information.

regards,
as

On 17 May 2012, at 13:00, Julian Reschke wrote:

> I'd also move the discussion of cache busting into an appendix, or not mention it at all; it's not specific to this protocol.

---

From: Julian Reschke <[email-masked]>
Date: Thu, 17 May 2012 19:22:20 +0200

On 2012-05-17 19:16, Arturo Servin wrote:
>
> I think it is important to mention it. Otherwise you will end up with
> different approaches to solve the problem for getting fresh information.
> ...

Well, the *right* way is to send Cache-Control.

"cache busting" using variations in the request-URI is just a hack that 
happens to work with broken caches.

Best regards, Julian

---

From: "John Levine" <[email-masked]>
Date: 17 May 2012 17:32:50 -0000

>Using URI templates sound promising.

I sure hope not.  URI templates are a reasonable way to try to put a
consistent layer on top of a bunch of existing inconsistent http
services.  But in this situation, where we're able to spec the URIs
from scratch, they're just an extra level of unneeded complexity and
cruft.

R's,
John

---

From: Julian Reschke <[email-masked]>
Date: Thu, 17 May 2012 19:39:55 +0200

> from scratch, they're just an extra level of unneeded complexity and

I have no problem with the protocol hardwiring things into URIs, if that 
can be done. But please stay away from the term "restful" then.

Best regards, Julian

---

From: Arturo Servin <[email-masked]>
Date: Thu, 17 May 2012 14:43:36 -0300

I found the solution interesting to deal with the problem using simple agents, but any decent agent should support adding this header.

	Point taken.

.as

On 17 May 2012, at 14:22, Julian Reschke wrote:

> "cache busting" using variations in the request-URI is just a hack that happens to work with broken caches.
> 
> Best regards, Julian

---

From: Andy Newton <[email-masked]>
Date: Thu, 17 May 2012 14:54:25 -0400

> Using URI templates sound promising.

This keeps coming up, but so far nobody has shown why it is useful. I think what we want out of URI templating is to be shown what utility it adds before placing it in the specifications.

> I don't follow. Servers need to process the Accept header field according to RFC 2616. Are you saying they can rely on it being simpler? In which case, this would need to be a "MUST NOT".

Uh, yeah. I think I'm trying to have it both ways. It's probably best to simply remove this.

> The method is probably ok, but the way it was explained was confusing: client specifies it wants "A", but server is allowed to return "B" (and label it as "B"), if it has out-of-band info that the client will understand it, too. Note that here "A" and "B" could be any media type (the label is really opaque).

Ok. I'll look into cleaning this up.

> Do not profile the base protocol unless there is a very very good reason.

I now understand what you are saying.

> There's still a set of characters that won't be usable in XML (yes, not even escaped).

That would be &, <, and >. So I guess we should mention those are to be escaped as well. Gosh XML is overly complex.

Thanks for the input.

-andy

---

From: Andy Newton <[email-masked]>
Date: Thu, 17 May 2012 18:56:27 +0000

Arturo,

Would you mind us moving and describing the technique in an appendix without reserving a specific parameter?
The technique would be to select a parameter unlikely to be used in the specification, such as "tenterhooksarekewl".

-andy

On May 17, 2012, at 1:43 PM, Arturo Servin wrote:

> _______________________________________________
> weirds mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/weirds

---

From: Andy Newton <[email-masked]>
Date: Thu, 17 May 2012 18:57:50 +0000

On May 17, 2012, at 1:39 PM, Julian Reschke wrote:

> I have no problem with the protocol hardwiring things into URIs, if that can be done. But please stay away from the term "restful" then.

Can you elaborate on this? Are you making a REST purity argument? I'm confused.
Sorry to be thick headed here.

-andy

---

From: "Hollenbeck, Scott" <[email-masked]>
Date: Thu, 17 May 2012 19:02:21 +0000

Isn't Julian suggesting that we not use the parameter-based approach at all?

Scott

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On
> Behalf Of Andy Newton
> Sent: Thursday, May 17, 2012 2:56 PM
> To: Arturo Servin
> Cc: <[email-masked]>
> Subject: Re: [weirds] feedback on draft-designteam-weirds-using-http
> 
> Arturo,
> 
> The technique would be to select a parameter unlikely to be used in the
> specification, such as "tenterhooksarekewl".
> 
> -andy
> 
> > 	I found the solution interesting to deal with the problem using
> simple agents, but any decent agent should support adding this header.
> >
> > 	Point taken.
> >
> > .as
> >
> >

---

From: Andy Newton <[email-masked]>
Date: Thu, 17 May 2012 19:07:24 +0000

Yeah. He also mentioned moving it to an appendix.
I'm just trying to find a compromise.

-andy

---

From: "Murray S. Kucherawy" <[email-masked]>
Date: Thu, 17 May 2012 19:19:35 +0000

> From: [email-masked] [mailto:[email-masked]] On Behalf Of Andy Newton
> Sent: Thursday, May 17, 2012 11:54 AM
> To: Julian Reschke
> Cc: [email-masked]
> This keeps coming up, but so far nobody has shown why it is useful. I
> think what we want out of URI templating is to be shown what utility it
> adds before placing it in the specifications.

Mark Nottingham made a good verbal argument for this in Paris, none of which I remember.  I've asked him to send me a summary of his points.  I'll forward it here when I get it.

This is important for what's going on in REPUTE as well, for the same reasons.

-MSK

---

From: Arturo Servin <[email-masked]>
Date: Thu, 17 May 2012 16:29:16 -0300

No problem.

Cheers,
as

---

From: Arturo Servin <[email-masked]>
Date: Thu, 17 May 2012 16:31:13 -0300

A bit late in reading.

	I do not have a strong argument against keep it, so if it is better to remove it all, it is ok to me.

Regards,
.as

---

From: Julian Reschke <[email-masked]>
Date: Thu, 17 May 2012 21:34:13 +0200

> Sorry to be thick headed here.

If you hard-wire the URI format, and there's no discovery whatsoever, 
you don't take advantage of <http://en.wikipedia.org/wiki/HATEOAS>.

Now my experience is that most of the time, discussions about whether 
something is "restful" aren't productive. It's not essential that 
everything is "restful". What's essential is that it works.

That's why I initially said that you should stay away from the term 
unless you really plan to fully embrace it :-).

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Thu, 17 May 2012 21:37:30 +0200

On 2012-05-17 20:54, Andy Newton wrote:
> That would be&,<, and>. So I guess we should mention those are to be escaped as well. Gosh XML is overly complex.
> ...

No :-).

JSON allows all C0 control characters. XML only allows TAB, CR, and LF. 
You can't represent the others in plain XML (you can always invent 
*another* escaping syntax on top of XML, though).

And no, XML is not overly complex. It just has certain constraints that 
make sense for the things it was designed for.

Best regards, Julian

---

From: Andy Newton <[email-masked]>
Date: Thu, 17 May 2012 16:02:06 -0400

On May 17, 2012, at 3:37 PM, Julian Reschke wrote:

> JSON allows all C0 control characters. XML only allows TAB, CR, and LF. You can't represent the others in plain XML (you can always invent *another* escaping syntax on top of XML, though).

Reading section 2.5 of RFC 4627, it says x00 - x1F (the C0 set from what I understand) must be escaped.
The XML would have to be XML 1.1, not XML 1.0. Is that what you are getting at?

-andy

---

From: Julian Reschke <[email-masked]>
Date: Thu, 17 May 2012 22:07:22 +0200

> The XML would have to be XML 1.1, not XML 1.0. Is that what you are getting at?

Right, it might work with XML 1.1, but nobody is using XML 1.1. It's 
dead for all practical purposes. Don't go near it.

Best regards, Julian

---

From: Andy Newton <[email-masked]>
Date: Thu, 17 May 2012 20:10:20 +0000

On May 17, 2012, at 3:34 PM, Julian Reschke wrote:

> If you hard-wire the URI format, and there's no discovery whatsoever, you don't take advantage of <http://en.wikipedia.org/wiki/HATEOAS>.
> 
> Now my experience is that most of the time, discussions about whether something is "restful" aren't productive. It's not essential that everything is "restful". What's essential is that it works.
> 
> That's why I initially said that you should stay away from the term unless you really plan to fully embrace it :-).

We are using the term RESTful and not REST, which is generally interpreted as borrowing from REST but not being totally compliant to the principles.

-andy

---

From: Francisco Obispo <[email-masked]>
Date: Thu, 17 May 2012 13:13:07 -0700

If you need to specify non-ascii characters in an XML document, you either have to:

a) Encode the characters in their XML entities ñ -> &#241;  or

b) use a CDATA instruction: Unparsed Character Data [1]

[1] http://www.w3schools.com/xml/xml_cdata.asp

The latter approach seems to be more efficient for some.

On May 17, 2012, at 12:37 PM, Julian Reschke wrote:

> And no, XML is not overly complex. It just has certain constraints that make sense for the things it was designed for.
> 
> Best regards, Julian

Francisco Obispo 
email: [email-masked]
Phone: +1 650 423 1374 || INOC-DBA *3557* NOC
PGP KeyID = B38DB1BE

---

From: Julian Reschke <[email-masked]>
Date: Thu, 17 May 2012 22:15:02 +0200

> We are using the term RESTful and not REST, which is generally interpreted as borrowing from REST but not being totally compliant to the principles.

Citation needed.

In doubt, consult <http://isitrestful.com/> :-)

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Thu, 17 May 2012 22:24:20 +0200

> a) Encode the characters in their XML entities ñ ->  &#241;  or

1) You can use those "as-is", if you declare the document encoding 
properly (such as by using UTF-8).

2) That doesn't change the repertoire of characters you can use.

3) Also, it's ASCII control characters which are a problem.

> [1] http://www.w3schools.com/xml/xml_cdata.asp

-> <http://w3fools.com/>

> The latter approach seems to be more efficient for some.

And it doesn't help at all. In CDATA, you don't need to escape "<" and 
"&", but in turn there are *other* sequences you can't use. See 
<http://www.w3.org/TR/REC-xml/#sec-cdata-sect> -- you can't have the 
string "]]>" inside CDATA because it ends the CDATA section.

My recommendation is never ever to use CDATA unless when hand-editing 
*and* when you absolute positively know what you do. If you generate 
with a program, don't ever use it.

Best regards, Julian

---

From: Francisco Obispo <[email-masked]>
Date: Thu, 17 May 2012 13:53:33 -0700

Did a bit more research and http://www.w3.org/International/questions/qa-controls proposes what I had in mind, which is encoding the content using something like base64 and decoding it before presentation. (ugly)

I might be missing something, but why are we arguing about this? I don't think we're planning to pass control codes within the XML.. 

Francisco

On May 17, 2012, at 1:24 PM, Julian Reschke wrote:

> 1) You can use those "as-is", if you declare the document encoding properly (such as by using UTF-8).
> 
> And it doesn't help at all. In CDATA, you don't need to escape "<" and "&", but in turn there are *other* sequences you can't use. See <http://www.w3.org/TR/REC-xml/#sec-cdata-sect> -- you can't have the string "]]>" inside CDATA because it ends the CDATA section.
> 
> My recommendation is never ever to use CDATA unless when hand-editing *and* when you absolute positively know what you do. If you generate with a program, don't ever use it.
> 
> Best regards, Julian

Francisco Obispo 
email: [email-masked]

---

From: SM <[email-masked]>
Date: Thu, 17 May 2012 15:00:02 -0700

Hi Arturo,
At 10:43 17-05-2012, Arturo Servin wrote:
>         I found the solution interesting to deal with the problem 
> using simple agents, but any decent agent should support adding this header.

The problem is generally "middleboxes".

Regards,
-sm

P.S. I'll defer to Julian

---

From: Julian Reschke <[email-masked]>
Date: Fri, 18 May 2012 08:49:53 +0200

> I might be missing something, but why are we arguing about this? I don't think we're planning to pass control codes within the XML..

I raised the point because the text is incomplete. If you state that the 
value never contain control characters beyond TAB CR LF, the problem 
goes indeed away.

Best regards, Julian

---

From: Maarten Wullink <[email-masked]>
Date: Wed, 30 May 2012 07:13:32 +0000

I would suggest removing the versioning information from the content-type.
Put the version information in the URL itself, like this where "v1" is the version 1 of the API.

/base/v1/domains/example.com

This way is clear what version of the API the client is connecting to and you do
Not have to abuse the content-type for this.

For more about versioning see:
http://blog.apigee.com/taglist/versioning

application\weirds_blah_v1+json

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Andy Newton
Sent: donderdag 17 mei 2012 20:54
To: Julian Reschke
Cc: [email-masked]
Subject: Re: [weirds] feedback on draft-designteam-weirds-using-http

Thanks for the input.

-andy

---

From: Andy Newton <[email-masked]>
Date: Wed, 30 May 2012 20:48:02 -0400

Maarten,

Using media types for versioning RESTful interfaces has been quite common in the industry for years. I would hardly call it abusive. Here is an old post by Peter Williams on the subject: 
http://barelyenough.org/blog/2008/05/versioning-rest-web-services/

Looking around though, it would seem that use the level extension is a way of using the Accept/Content-Type headers without encoding the version in the media type itself. See: 
http://techbits.blogspot.com/2012/02/versioning-restful-apis-there-seems-to.html

Though level is not explicitly specified in the Content-Type header definition, the syntax is legal as a parameter the same as it is specified in the Accept header. This seems like a decent approach.

-andy