re: https://twitter.com/apiblueprint/status/374456335846612992

mt-version.md

re: https://twitter.com/apiblueprint/status/374456335846612992

Media-type equivalence

application/json;charset=utf-8
application/json;     charset=utf-8
application/json;     charset="utf-8"
application/json // since JSON's default unicode charset is UTF-8

Not many, ~ if any, clients/servers are able to handle all combinations and their equivalence. I'll cut it short: decisions shouldn't be driven imho by current failures.. I meant current implementations, but in the case of version, within the mindset of a very convoluted HTTP grammar, I fall on the KISS side.

Media-type parameters

From here:

Parameters are modifiers of the media subtype, and as such do not
fundamentally affect the nature of the content.  The set of
meaningful parameters depends on the media type and subtype.  Most
parameters are associated with a single specific subtype.  However, a
given top-level media type may define parameters which are applicable
to any subtype of that type.  Parameters may be required by their
defining media type or subtype or they may be optional.  MIME
implementations must also ignore any parameters whose names they do
not recognize.

So does version affect fundamentaly the nature of the content? I'd say so due to breaking changes, but the floor is open to interpretation.

@andreineculau, thank you for bringing this discussion to the table!

I totally understand and copy on the point you have made in media-type equivalence. The version parameter is indeed optional and where omitted the latest available version on the given system should be used.

However as we will mature the format changes, including those, not backward compatible will inevitably happen. Furthermore this parameter is dubbed under the _version: <AST version> in a serialized format. And as you can see more consistency problems might dwell here.

All in all it is really a question about growing a Media Type. Would you suggest to leave versioning completely out of both the Media Type and a serialization? Am I just unnecessarily afraid of possible future changes?

Thank you for your input! Much appreciated.

@andreineculau My pragmatic goals:

• We need serialisation to be forward compatible as much as possible
• This is important not only for tooling, but for us as well; we do have old ASTs in our database that we want to be able to read using our tooling
• This is largely satisfied by version attribute present in serialisation format. Thus it can be exchanged between toolings without any need for associated metadata
• Main goal of MIME for me is content negotiation; Apiary API should be able to provide blueprint AST in format compatible with client side
• For that case, it makes sense to me to have version as parameter; AST should fundamentally be same, but it will be extended in superset ways

I'd say what might make sense is to have major versions directly in media type and roll "big changes" (= those that are not superset, but changes/renames structure in significant way) by changing it. Everything else should be compatible and thus modified by parameter.

But, being on KISS side, I'd not overcomplicate it and just push everything into parameter ;)

Thoughts?

P.S.: All your three examples are invalid

Optional

Aha, from the tweets, I concluded that you require the version parameter.

But in any case - defaulting to the newest version brought up lots of discussions in my neighborhood, because it invites to errors. The only case where it makes sense is when you have a crawler of sorts, but most of the times, you want to do smth with the data that conforms to a semantic MT (not just syntax MT like application/json) and then you cannot just say "give me anything, or give me something that looks like X" - the 2 alternatives are actually equivalent because Xv1 can be totally different than Xv2, and not just granularly different.

Versioning

I am totally with you, @zdne - I think progress should not be hindered by stupidly forcing yourself to be backward compatible forever, or stupidly forcing yourself to say "this is not a new version, this is an entirely new concept" and start looking in the thesaurus for synonyms for a "same, same, but different" MT :) vivid experience

The reasoning of me @ Klarna ending up with v1 inside the MT is linked to the Optional section above, and primarily to the end of that paragraph. The linkage between andrei-v1 and andrei-v2 is on a conceptual level - they both talk about a similar "it" but at 2 different time frames. Those 2 could be as different if not even more different than andrei-v1 and vnd.neculau.andrei-v1. Same for andrei+json and andrei+xml - despite being very easy to assume that it is only the syntax that is different, changes may arise, subtle or not. That is to say that "andrei" as a standalone reference doesn't mean anything.

Or if I turn it to your case, into a question: what does vnd.apiblueprint.ast.raw media-type stands for? Is it possible to make any descriptions/assumptions of it that will not change? ever? Like in the case of "application/json; profile=http://profiles.apiblueprint.org/ast" - it's always a valid JSON encoded string, regardless of the parameter profile. Reading @Almad's reply - "v0" is the core, and v1 is a superset of v0, etc. which then makes sense if his "SHOULD fundamentally be same" is what IETF thinks it is :) , but that's not the feeling I got from @zdne

Version dubbing

Nothing wrong with that, beyond the dubbing itself. In most cases I would find it weird though to make the meta-data (read: at least the Content-Type header) lost when "saving" the AST somewhere. So, if I'd save an AST somewhere, I'd save it as

{
  "type": "application/vnd.apiblueprint.ast.raw",
  "ast": ...
}

or more in line with your structure

{
  "_content_type": "application/vnd.apiblueprint.ast.raw",
  ...
}

So, in my "square-cornered post-dictatorship world" :) I'd duplicate the entire media-type, and not just the version in the payload (since the intention is to have these ASTs as files). I don't know if you have to, but how do you separate between the ASTs with markdown or the HTML descriptions?

Granularity of changes - Almad's last paragraph

I have to say I agree with all of it, letter by letter - except the ending :) "push everything into parameter".
Instead I'd push the version inside the MT, based on the reasoning in the above Version section, but with one clarification: adding stuff to the structure is not a breaking change, and in my world I do not version that change. At all. I only version breaking changes.

Say https://gist.github.com/zdne/6355511 wouldn't have description, but one day you decide to add it. All current parsers will just say "so what?" and ignore it.

DEKUJI MOC for the discussion :)

and also for the application/json article :) - I was aware of it, but the whole thing didn't really sink in for me, especially after reading the thread of a nice bugzilla issue (keywords: charset header microsoft german) regarding (not) sending the charset parameter automatically - but I cannot find it now :( #twitter #google #cueup #delicious #fail

but hands-on about the article

1. "smelling" anything, in general -> "puke"
2. the article targets 2 media-types, while browsers or any user-agent in general should work a bit more generic and thus append the charset parameter no matter the media-type (despite that parameter not being defined, or worse - maybe it conflicts with some weird media-type). Disclaimer - it's exactly what his last sentence says, but his sentence sound like nitpicking - what else could the charset parameter mean? :)
3. "URI encoding mimetype" -> if I request something with Accept-Charset that is far from KNOWING that the response charset uses the same value that I requested. And I have no idea why the author thinks servers will default to utf-8 . Maybe the majority of them do, based on common-sense, but there is absolutely nothing written anywhere that gives substantial power to that