Custom Media Types

[Hennadii Omelchenko]

Roy Fielding talks a lot about media types (for example, here ). But what I've noticed is that people in this groups (and similar) almost never talk about custom media types for their specific APIs, but talk about some general hypermedia formats (like HAL, Syren and others).

So, my question would be. Has an initial role and value of media types been eroded over recent years and we as a community don't want to have custom media types defined (describing 'processing rules', link rels etc) or am I missing something in this regard? Shouldn't we start designing a new API with a media type design (even based on some existing one or extending existing one)?

[Dmitry Pavlov]

The problem with custom media type is that you will need also a custom client that can understand it. When a client receives response with content-type: application/vnd.my-syper-type it can't make any assumptions about it.  If it json based or not and where to find links. Along with it client should understand semantics of message (i.e. "what is this field means?")

When you use a standard type you can leverage this problem and if the client knows about type, it can work with multiple apps and only needs to understand semantics of each. For semantics you can define your profile instead of defining whole media type.

If it's ok for you, there is not a crime to use custom one.

For me it is not erosion it's direction to code reuse :)

10.04.2014 13:08 пользователь "Hennadii Omelchenko" <hennadii....@gmail.com> написал:

Roy Fielding talks a lot about media types (for example, here ). But what I've noticed is that people in this groups (and similar) almost never talk about custom media types for their specific APIs, but talk about some general hypermedia formats (like HAL, Syren and others).

So, my question would be. Has an initial role and value of media types been eroded over recent years and we as a community don't want to have custom media types defined (describing 'processing rules', link rels etc) or am I missing something in this regard? Shouldn't we start designing a new API with a media type design (even based on some existing one or extending existing one)?

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Hennadii Omelchenko]

Dmitriy,

I think to the contrary. You can support generic media types for generic clients such as HAL browser. But they are pretty much useless (at least in M2M solutions, but I believe others, too) without knowing the other part of the contract.

But isn't there always implicit conventions behind these generic media types? Possible link relations, expected data formats, other rules and so on. Custom media type would make this particular contract explicitly defined (again, can refer here to the original post of Fielding's). 

And another point. I've always believed that media types are far more that just a response format, but a general contract of API including format, other aspects mentioned above and more, guess this can be found in the original work on REST and some other sources.

Четвер, 10 квітня 2014 р. 12:08:46 UTC+3 користувач Hennadii Omelchenko написав:

[Philip Nelson]

Using HAL or Cj etc doesn't imply you don't have a contract. For each link traversal you can explicitly establish a profile, that is the defined contract. So I'm not sure I understand the benefit of a custom media type for that part of the challenge. You would have to do the same thing, right?

--

[Hennadii Omelchenko]

Philip,

1.  HAL or Cj by themselves don't imply any 'my domain specific contract', that's what I'm talking about.
   
2. yes, you can define profiles, but anyways a client HAS to know about relation types beforehand (especially, in M2M)
   
3. Yes, I agree that profiles in general allow accomplishing goal. But... 
   
1. they are not a standart feature (aren't they? No approved standard at least)
   
2. many questions as to how use them properly (lots of blogs on this subject proves this point), no best practices.

At the same time media types are well defined and mature enough to use, and I believe that's why they have been used for Web. So, why do we need to invent the bicycle? Why to be so reluctant to them? Are there any significant drawbacks? Other reasons not to use them?

Четвер, 10 квітня 2014 р. 14:35:11 UTC+3 користувач Philip Nelson написав:

[Philip Nelson]

Hennadii, I think if these generic media types like I think of html, or of generic collections in 3GL's, It provides some of the

things everybody needs and defines that part of the contract. HTML does define profiles so this is not a new concept, just

new in how it's used in a json or xml based api. 

So a custom media type is fine, and I even noticed that the new HAL based amazon app streaming service defined a new

media type in spite of being HAL based. As mentioned earlier, you are given a base set of features all hypermedia 

api's should do, so (throwin' back at ya!) why reinvent the wheel? ;-)

[Dmitry Pavlov]

At least idea is the following:

Custom media-type.

TODO LIST:

1. invent data format

2. invent semantics of messages

3. write server impl. You need to implement format (parsing + message generation) and business logic

4. write client. You need to implement format (parsing + message generation) and business logic

Common media-type.

TODO LIST:

1. select media-type that suits your needs

2. invent semantics

3. write server impl. you need to implement business logic

4. write server impl. you need to implement business logic

as you can see even if we are not talking about smart clients, the second solution can be easier in at the step #1 and a bit easier at #3 and #4 (assuming the language you use have libraries that support selected media-types). So if you don't believe in smart clients autoparsing profiles that will help you to implement business logic, you can think about it as just a helper (you don't need to think about hypermedia placement and so on).

As to profiles, there is an RFC for such link relation: http://tools.ietf.org/html/rfc6906, so it's there is a standard way to point to it.

Now back to implementation details. It does not matter for what to apply business semantics: custom format or not, maybe sometimes custom type can be compact, because nobody can stop you to make a shortcut :).

I think the people face problems with common types because it seems strange to fullfill mediatype with additional constraints that you're missing (i.e. how to update a resource in HAL, there is any statement in spec for it). So they think "I better invent format from scratch them will try to add rules and constraints I'm missing" and here we go another custom media type.

I'd like to point out that I don't "standard hypermedia only" advocate, of course sometimes custom format can be a mandatory, but not for every case

С уважением,
Дмитрий Павлов