Hi folks. I hope you had a nice christmas with you friends and families - and
are ready for yet a season of Rest-Discus :-)

Sorry for bringing up an old issue; I have trawled through earlier discussions
but haven't found any conclusive posts that solves the problem.

Assume we have a resource with a sales order. Such a sales order can be
represented for an end-user as either HTML or a spreadsheet. With content
negotiation thats easily done with accept headers for text/html or
application/vnd.ms-excel (or similar). But browsers don't let the end-user
switch accept headers, so instead we define HTML as the default type, and add a
link to where the spreadsheet can be downloaded.

Now we add M2M support and decide to represent the sales order in HAL or maybe
even in HTML using RDFa or some microformat. But we must support two different
ways of embedding domain specific data - either the (fictional) Scandinavian
Sales Order Vocabulary or the (also fictional) US Sales Order Vocabulary. How
should we approach that problem?

First of all, we cannot do content negotiation and switch on the media type
because 1) we don't want to mint new domain specific media types, and 2) because
we want to use the same media type but with different vocabularies/schemas.

Second, the prerequisites might even be wrong: is supporting multiple
vocabularies the right thing to do? Lets assume it is right and continue on (but
you are most welcome to question this!).

I can see two different approaches:

1) Switch on another HTTP header (but which one? accept-language? a custom one?)

2) Use different URIs for different vocabularies (as with the browser solution).

3) Include both vocabularies in the response.

If different URIs are used then we need to be able to discover them. This could
be done with a link header/HTML anchors + link relation types. The downside is
(as always with different URIs) that we don't have one single URL that
represents the sales order - unless we accept the overhead of always doing a
two-step fetch, and store the base URI, fetch that, look for link-rels and fetch
the required representation.

Personally I would rather avoid the two-step fetch and do vocabulary negotiation
using headers - but, on the other hand, this is perfectly acceptable in a
browser-based scenario, so why not also use it in M2M scenarios (caching of the
first step would even reduce the problem).

Somehow it seems like HTTP is missing a way of doing sub-content negotiation,
where the request defines the accepted media type, and together with this also
defines the acceptable sub-content-format/vocabulary.

According to RFC 2616 (HTTP 1.1) the accept header can take a rather generic
extension ";token = token" (for instance ";level=1"), but the standard fails to
explain what it is supposed to be used for. Can it be used for exactly the
scenario above?

Comments?

Thanks, Jørn

Hi Jørn,

On 12/27/2011 10:40 AM, Jorn Wildt wrote:

[skip]

> Now we add M2M support and decide to represent the sales order in HAL or
> maybe even in HTML using RDFa or some microformat. But we must support
> two different ways of embedding domain specific data - either the
> (fictional) Scandinavian Sales Order Vocabulary or the (also fictional)
> US Sales Order Vocabulary. How should we approach that problem?
>

You can do this by utilising RDF(a) and provide knowledge
representations that utilise both vocabularies at once (sidy by side),
i.e., the result would be a kind of duplicated knowledge
representations. Or you can provide a mapping between both vocabularies,
deliver your information by only utilising one vocabulary, and provide
further information that make the machine client aware of the vocabulary
mapping (a rather generic property for this is rdfs:seeAlso).

> First of all, we cannot do content negotiation and switch on the media
> type because 1) we don't want to mint new domain specific media types,
> and 2) because we want to use the same media type but with different
> vocabularies/schemas.

I wouldn't recommend to switch the media type, but to utilise a rather
generic media type instead.

>
> Second, the prerequisites might even be wrong: is supporting multiple
> vocabularies the right thing to do? Lets assume it is right and continue
> on (but you are most welcome to question this!).

I guess, this depends on the intended clients. They have to know how to
process retrieved information (incl. their vocabularies). In a kind of
ideal open world with "shared meaning" and "shared understanding", maybe
one vocabulary would be enough, e.g., the rather generic GoodRelations
Vocabulary for e-commerce.

Cheers,


Bo


PS: I do not know the content of your mentioned vocabularies. However,
by reading their names it rather looks like a localisation problem (or
maybe a wrong vocabulary design; e.g. do not design to close).

On Dec 27, 2011, at 10:40 AM, Jorn Wildt wrote:

> Assume we have a resource with a sales order. Such a sales order can be
represented for an end-user as either HTML or a spreadsheet. With content
negotiation thats easily done with accept headers for text/html or
application/vnd.ms-excel (or similar). But browsers don't let the end-user
switch accept headers, so instead we define HTML as the default type, and add a
link to where the spreadsheet can be downloaded.
>
> Now we add M2M support and decide to represent the sales order in HAL or maybe
even in HTML using RDFa or some microformat. But we must support two different
ways of embedding domain specific data - either the (fictional) Scandinavian
Sales Order Vocabulary or the (also fictional) US Sales Order Vocabulary. How
should we approach that problem?

Why don't you leverage an existing format, UBL in this case? UBL has no
associated media type (yet) but that should not stop you from going ahead an
minting a name for your purposes.

>
> First of all, we cannot do content negotiation and switch on the media type
because 1) we don't want to mint new domain specific media types,

I'd suggest you do. It has no significant cost and allows you to work within the
Web's architecture with easy. Why create fixes for problems that do not exist?
(Smells enterprisey :-)

> and 2) because we want to use the same media type but with different
vocabularies/schemas.

Huh?

>
> Second, the prerequisites might even be wrong: is supporting multiple
vocabularies the right thing to do? Lets assume it is right and continue on (but
you are most welcome to question this!).

My personal advice: Embrace the Web, do simple, straight forward stuff and defer
fixing problems until the exist (e.g. why do you consider media type bloat a
problem?)

Applying REST to enterprise IT problems does not mean tweaking REST, it means
changing your view of the problem.

>
> I can see two different approaches:
>
> 1) Switch on another HTTP header (but which one? accept-language? a custom
one?)

No

>
> 2) Use different URIs for different vocabularies (as with the browser
solution).

That is always good design. Variants should be given their own URIs. Explore
Content-Location header aspects for this.

>
> 3) Include both vocabularies in the response.

No

>
> If different URIs are used then we need to be able to discover them. This
could be done with a link header/HTML anchors + link relation types.

Check the Alternates header

> The downside is (as always with different URIs) that we don't have one single
URL that represents the sales order - unless we accept the overhead of always
doing a two-step fetch, and store the base URI, fetch that, look for link-rels
and fetch the required representation.

No problems here - see all hints above. Conneg already handles these things
well. (Digest the all the specs before you optimize ;-)

>
> Personally I would rather avoid the two-step fetch and do vocabulary
negotiation using headers - but, on the other hand, this is perfectly acceptable
in a browser-based scenario, so why not also use it in M2M scenarios (caching of
the first step would even reduce the problem).

See above; HTTP & friends already give you all you need.

>
> Somehow it seems like HTTP is missing a way of doing sub-content negotiation,
where the request defines the accepted media type, and together with this also
defines the acceptable sub-content-format/vocabulary.

There is AFAIK no notion of 'sub-content-format/vocabulary'. If you must insist
on sth like this, check specs like Accept-Features header or the various
Profile-mechanisms. (Sorry, no time to dig up the links).

>
> According to RFC 2616 (HTTP 1.1) the accept header can take a rather generic
extension ";token = token" (for instance ";level=1"), but the standard fails to
explain what it is supposed to be used for. Can it be used for exactly the
scenario above?
>
> Comments?
>

Think hard whether you actually have the problems you think you have. Meanwhile,
give the Enterpriseys in your team something else to chew on :-)


Jan

> Thanks, Jørn
>
>

> Why don't you leverage an existing format, UBL in this case?

That's cheating and avoiding the question :-) The assumption is that we actually
have two different formats to support. According to Wikipedia that is not even
so unrealistic - apparently there are regional variations of it
(http://en.wikipedia.org/wiki/Universal_Business_Language).

> > First of all, we cannot do content negotiation and switch on the media type
because 1) we don't want to mint new domain specific media types,
>
> I'd suggest you do. It has no significant cost and allows you to work within
the Web's architecture with easy.

It should be obvious, from the previous discussions in this group, that
different schools exists regarding this issue. Right now I am trying to make up
my own mind whether I belong to one or the other school. This question is for
the "do not mint new media types"-school.

> (e.g. why do you consider media type bloat a problem?)

I haven't yet decided whether it is a problem or not :-) Right now I am
exploring the consequences of the different approaches. One thing that bothers
me though, is that media types are considered protocol layer information. For me
that means putting domain specific knowledge into it is like asking the TCP/IP
stack to be aware of Cats, Dogs, Sales orders and what ever else we come up
with.

Thanks for the pointers to other headers!

/Jørn

--- In rest-discuss@yahoogroups.com, Jan Algermissen <jan.algermissen@...>
wrote:
>
>
> On Dec 27, 2011, at 10:40 AM, Jorn Wildt wrote:
>
> > Assume we have a resource with a sales order. Such a sales order can be
represented for an end-user as either HTML or a spreadsheet. With content
negotiation thats easily done with accept headers for text/html or
application/vnd.ms-excel (or similar). But browsers don't let the end-user
switch accept headers, so instead we define HTML as the default type, and add a
link to where the spreadsheet can be downloaded.
> >
> > Now we add M2M support and decide to represent the sales order in HAL or
maybe even in HTML using RDFa or some microformat. But we must support two
different ways of embedding domain specific data - either the (fictional)
Scandinavian Sales Order Vocabulary or the (also fictional) US Sales Order
Vocabulary. How should we approach that problem?
>
> Why don't you leverage an existing format, UBL in this case? UBL has no
associated media type (yet) but that should not stop you from going ahead an
minting a name for your purposes.
>
> >
> > First of all, we cannot do content negotiation and switch on the media type
because 1) we don't want to mint new domain specific media types,
>
> I'd suggest you do. It has no significant cost and allows you to work within
the Web's architecture with easy. Why create fixes for problems that do not
exist? (Smells enterprisey :-)
>
> > and 2) because we want to use the same media type but with different
vocabularies/schemas.
>
> Huh?
>
> >
> > Second, the prerequisites might even be wrong: is supporting multiple
vocabularies the right thing to do? Lets assume it is right and continue on (but
you are most welcome to question this!).
>
> My personal advice: Embrace the Web, do simple, straight forward stuff and
defer fixing problems until the exist (e.g. why do you consider media type bloat
a problem?)
>
> Applying REST to enterprise IT problems does not mean tweaking REST, it means
changing your view of the problem.
>
> >
> > I can see two different approaches:
> >
> > 1) Switch on another HTTP header (but which one? accept-language? a custom
one?)
>
> No
>
> >
> > 2) Use different URIs for different vocabularies (as with the browser
solution).
>
> That is always good design. Variants should be given their own URIs. Explore
Content-Location header aspects for this.
>
> >
> > 3) Include both vocabularies in the response.
>
> No
>
> >
> > If different URIs are used then we need to be able to discover them. This
could be done with a link header/HTML anchors + link relation types.
>
> Check the Alternates header
>
> > The downside is (as always with different URIs) that we don't have one
single URL that represents the sales order - unless we accept the overhead of
always doing a two-step fetch, and store the base URI, fetch that, look for
link-rels and fetch the required representation.
>
> No problems here - see all hints above. Conneg already handles these things
well. (Digest the all the specs before you optimize ;-)
>
> >
> > Personally I would rather avoid the two-step fetch and do vocabulary
negotiation using headers - but, on the other hand, this is perfectly acceptable
in a browser-based scenario, so why not also use it in M2M scenarios (caching of
the first step would even reduce the problem).
>
> See above; HTTP & friends already give you all you need.
>
> >
> > Somehow it seems like HTTP is missing a way of doing sub-content
negotiation, where the request defines the accepted media type, and together
with this also defines the acceptable sub-content-format/vocabulary.
>
> There is AFAIK no notion of 'sub-content-format/vocabulary'. If you must
insist on sth like this, check specs like Accept-Features header or the various
Profile-mechanisms. (Sorry, no time to dig up the links).
>
> >
> > According to RFC 2616 (HTTP 1.1) the accept header can take a rather generic
extension ";token = token" (for instance ";level=1"), but the standard fails to
explain what it is supposed to be used for. Can it be used for exactly the
scenario above?
> >
> > Comments?
> >
>
> Think hard whether you actually have the problems you think you have.
Meanwhile, give the Enterpriseys in your team something else to chew on :-)
>
>
> Jan
>
> > Thanks, Jørn
> >
> >
>

On Dec 27, 2011, at 1:13 PM, Jorn Wildt wrote:

> > Why don't you leverage an existing format, UBL in this case?
>
> That's cheating and avoiding the question :-) The assumption is that we
actually have two different formats to support. According to Wikipedia that is
not even so unrealistic - apparently there are regional variations of it
(http://en.wikipedia.org/wiki/Universal_Business_Language).

Then I maybe misread your question - I did not understand your were focussing on
handing the regional variants. OTH, I'd start with the assumption that two
variants are needed. Can't you a) control the format in the first place or b)
allow for the variations within the same overall format? And let the client
figure out its desired data?

>
> > > First of all, we cannot do content negotiation and switch on the media
type because 1) we don't want to mint new domain specific media types,
> >
> > I'd suggest you do. It has no significant cost and allows you to work within
the Web's architecture with easy.
>
> It should be obvious, from the previous discussions in this group, that
different schools exists regarding this issue.

I don't think that there are really two schools when it comes to embedding stuff
like complete order data within e.g. HTML. Maybe post an example how this would
look?

> Right now I am trying to make up my own mind whether I belong to one or the
other school. This question is for the "do not mint new media types"-school.
>
> > (e.g. why do you consider media type bloat a problem?)
>
> I haven't yet decided whether it is a problem or not :-) Right now I am
exploring the consequences of the different approaches. One thing that bothers
me though, is that media types are considered protocol layer information. For me
that means putting domain specific knowledge into it is like asking the TCP/IP
stack to be aware of Cats, Dogs, Sales orders and what ever else we come up
with.

Note that HTTP *is* the application layer. It is not transport. The need for
media types is simply the consequence of the uniform interface. Knowing about
cats is just the same as knowing about images of style sheets in the HTML case.
Its fine.

Just don't describe functionality (what a server will actually *do) in the media
type.

>
> Thanks for the pointers to other headers!
>

I think example messages would help to communicate your 'problem'.

Jan

> /Jørn
>
> --- In rest-discuss@yahoogroups.com, Jan Algermissen <jan.algermissen@...>
wrote:
> >
> >
> > On Dec 27, 2011, at 10:40 AM, Jorn Wildt wrote:
> >
> > > Assume we have a resource with a sales order. Such a sales order can be
represented for an end-user as either HTML or a spreadsheet. With content
negotiation thats easily done with accept headers for text/html or
application/vnd.ms-excel (or similar). But browsers don't let the end-user
switch accept headers, so instead we define HTML as the default type, and add a
link to where the spreadsheet can be downloaded.
> > >
> > > Now we add M2M support and decide to represent the sales order in HAL or
maybe even in HTML using RDFa or some microformat. But we must support two
different ways of embedding domain specific data - either the (fictional)
Scandinavian Sales Order Vocabulary or the (also fictional) US Sales Order
Vocabulary. How should we approach that problem?
> >
> > Why don't you leverage an existing format, UBL in this case? UBL has no
associated media type (yet) but that should not stop you from going ahead an
minting a name for your purposes.
> >
> > >
> > > First of all, we cannot do content negotiation and switch on the media
type because 1) we don't want to mint new domain specific media types,
> >
> > I'd suggest you do. It has no significant cost and allows you to work within
the Web's architecture with easy. Why create fixes for problems that do not
exist? (Smells enterprisey :-)
> >
> > > and 2) because we want to use the same media type but with different
vocabularies/schemas.
> >
> > Huh?
> >
> > >
> > > Second, the prerequisites might even be wrong: is supporting multiple
vocabularies the right thing to do? Lets assume it is right and continue on (but
you are most welcome to question this!).
> >
> > My personal advice: Embrace the Web, do simple, straight forward stuff and
defer fixing problems until the exist (e.g. why do you consider media type bloat
a problem?)
> >
> > Applying REST to enterprise IT problems does not mean tweaking REST, it
means changing your view of the problem.
> >
> > >
> > > I can see two different approaches:
> > >
> > > 1) Switch on another HTTP header (but which one? accept-language? a custom
one?)
> >
> > No
> >
> > >
> > > 2) Use different URIs for different vocabularies (as with the browser
solution).
> >
> > That is always good design. Variants should be given their own URIs. Explore
Content-Location header aspects for this.
> >
> > >
> > > 3) Include both vocabularies in the response.
> >
> > No
> >
> > >
> > > If different URIs are used then we need to be able to discover them. This
could be done with a link header/HTML anchors + link relation types.
> >
> > Check the Alternates header
> >
> > > The downside is (as always with different URIs) that we don't have one
single URL that represents the sales order - unless we accept the overhead of
always doing a two-step fetch, and store the base URI, fetch that, look for
link-rels and fetch the required representation.
> >
> > No problems here - see all hints above. Conneg already handles these things
well. (Digest the all the specs before you optimize ;-)
> >
> > >
> > > Personally I would rather avoid the two-step fetch and do vocabulary
negotiation using headers - but, on the other hand, this is perfectly acceptable
in a browser-based scenario, so why not also use it in M2M scenarios (caching of
the first step would even reduce the problem).
> >
> > See above; HTTP & friends already give you all you need.
> >
> > >
> > > Somehow it seems like HTTP is missing a way of doing sub-content
negotiation, where the request defines the accepted media type, and together
with this also defines the acceptable sub-content-format/vocabulary.
> >
> > There is AFAIK no notion of 'sub-content-format/vocabulary'. If you must
insist on sth like this, check specs like Accept-Features header or the various
Profile-mechanisms. (Sorry, no time to dig up the links).
> >
> > >
> > > According to RFC 2616 (HTTP 1.1) the accept header can take a rather
generic extension ";token = token" (for instance ";level=1"), but the standard
fails to explain what it is supposed to be used for. Can it be used for exactly
the scenario above?
> > >
> > > Comments?
> > >
> >
> > Think hard whether you actually have the problems you think you have.
Meanwhile, give the Enterpriseys in your team something else to chew on :-)
> >
> >
> > Jan
> >
> > > Thanks, Jørn
> > >
> > >
> >
>
>

> > It should be obvious, from the previous discussions in this group, that
different schools exists regarding this issue.
>
> I don't think that there are really two schools when it comes to embedding
stuff like complete order data within e.g. HTML. Maybe post an example how this
would look?

Sorry if I wasn't clear about what "this issue" refers to: I was talking about
minting new domain specific media types. Like having a sales order specific
media type as for instance "application/vnd.mycompany.salesorder+xml".

> I think example messages would help to communicate your 'problem'.

Well, the examples are fictive from the start, so I cannot give that. As I said,
I am exploring the consequences of *not* minting new media types and wondering
how one would then do content/vocabulary negotiation.

/Jørn

On Dec 27, 2011, at 2:28 PM, Jorn Wildt wrote:
>
> Well, the examples are fictive from the start, so I cannot give that. As I
said, I am exploring the consequences of *not* minting new media types and
wondering how one would then do content/vocabulary negotiation.

Ah, ok. BTW, you name one reason here, how non-specific media types+link rels
and friends take away control that Web arch actually intends to give you).

Besides Accept-Features you could do sth. like this:

GET /orders/1
Accept: application/xhtml;profile=us-order

200 Ok
Content-Type: application/xhtml

However, I am not a fan of this because you loose visibility (media type
parameters other than 'q' are opaque to conneg) and you also do not know which
intermediary will silently strip the param (which it may).

I also think you simply end up creating the bloat you are trying to avoid in
another place (the profile or feature tag).

My advice remains: mint a media type, make it flexible enough to incorporate
whatever variations you might have and have the clients  deal with picking the
stuff they want.

Jan

P.S. You can also do Conneg on User-Agent but I have not yet made up my mind
whether that is a good idea.




>
> /Jørn
>
>

<snip>
I am exploring the consequences of *not* minting new media types and
wondering how one would then do content/vocabulary negotiation.
</snip>

It's not clear to me that *not* minting media types *requires*
content/vocabulary negotiation. why have you chosen to explore these
to things in this related way?

mca
http://amundsen.com/blog/
http://twitter.com@mamund
http://mamund.com/foaf.rdf#me




On Tue, Dec 27, 2011 at 10:45, Jan Algermissen
<jan.algermissen@...> wrote:
>
> On Dec 27, 2011, at 2:28 PM, Jorn Wildt wrote:
>>
>> Well, the examples are fictive from the start, so I cannot give that. As I
said, I am exploring the consequences of *not* minting new media types and
wondering how one would then do content/vocabulary negotiation.
>
> Ah, ok. BTW, you name one reason here, how non-specific media types+link rels
and friends take away control that Web arch actually intends to give you).
>
> Besides Accept-Features you could do sth. like this:
>
> GET /orders/1
> Accept: application/xhtml;profile=us-order
>
> 200 Ok
> Content-Type: application/xhtml
>
> However, I am not a fan of this because you loose visibility (media type
parameters other than 'q' are opaque to conneg) and you also do not know which
intermediary will silently strip the param (which it may).
>
> I also think you simply end up creating the bloat you are trying to avoid in
another place (the profile or feature tag).
>
> My advice remains: mint a media type, make it flexible enough to incorporate
whatever variations you might have and have the clients  deal with picking the
stuff they want.
>
> Jan
>
> P.S. You can also do Conneg on User-Agent but I have not yet made up my mind
whether that is a good idea.
>
>
>
>
>>
>> /Jørn
>>
>>
>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

On Dec 27, 2011, at 4:51 PM, mike amundsen wrote:

> <snip>
> I am exploring the consequences of *not* minting new media types and
> wondering how one would then do content/vocabulary negotiation.
> </snip>
>
> It's not clear to me that *not* minting media types *requires*
> content/vocabulary negotiation. why have you chosen to explore these
> to things in this related way?

AFAIU Jorn (thinks he) needs different (sort of distinct) formats for different
consumers. When shoving both variants in a single host media type he (thinks he)
needs a means to negotiate between them based on the consumer.

Jan



>
> mca
> http://amundsen.com/blog/
> http://twitter.com@mamund
> http://mamund.com/foaf.rdf#me
>
> On Tue, Dec 27, 2011 at 10:45, Jan Algermissen
> <jan.algermissen@...> wrote:
> >
> > On Dec 27, 2011, at 2:28 PM, Jorn Wildt wrote:
> >>
> >> Well, the examples are fictive from the start, so I cannot give that. As I
said, I am exploring the consequences of *not* minting new media types and
wondering how one would then do content/vocabulary negotiation.
> >
> > Ah, ok. BTW, you name one reason here, how non-specific media types+link
rels and friends take away control that Web arch actually intends to give you).
> >
> > Besides Accept-Features you could do sth. like this:
> >
> > GET /orders/1
> > Accept: application/xhtml;profile=us-order
> >
> > 200 Ok
> > Content-Type: application/xhtml
> >
> > However, I am not a fan of this because you loose visibility (media type
parameters other than 'q' are opaque to conneg) and you also do not know which
intermediary will silently strip the param (which it may).
> >
> > I also think you simply end up creating the bloat you are trying to avoid in
another place (the profile or feature tag).
> >
> > My advice remains: mint a media type, make it flexible enough to incorporate
whatever variations you might have and have the clients  deal with picking the
stuff they want.
> >
> > Jan
> >
> > P.S. You can also do Conneg on User-Agent but I have not yet made up my mind
whether that is a good idea.
> >
> >
> >
> >
> >>
> >> /Jørn
> >>
> >>
> >
> >
> >
> > ------------------------------------
> >
> > Yahoo! Groups Links
> >
> >
> >
>

<snip>
> AFAIU Jorn (thinks he) needs different (sort of distinct) formats for
different consumers. When shoving both variants in a single host media type he
(thinks he) needs a means to negotiate between them based on the consumer.
</snip>

Jorn: you are contemplating a single media-type w/ multiple negotiable
"formats"? is that right?

one, i don't understand the use of the word "format" here (in my mind
XML, JSON, CSV are formats so i need help here)
two, if you are using a single media type, what aspect of the
representation response are you planning on "negotiating"?
three, what kinds of _consumers_ are you contemplating that would use
the same media type, but need/want to negotiate for different
"formats"?

mca
http://amundsen.com/blog/
http://twitter.com@mamund
http://mamund.com/foaf.rdf#me




On Tue, Dec 27, 2011 at 14:37, Jan Algermissen
<jan.algermissen@...> wrote:
>
> On Dec 27, 2011, at 4:51 PM, mike amundsen wrote:
>
>> <snip>
>> I am exploring the consequences of *not* minting new media types and
>> wondering how one would then do content/vocabulary negotiation.
>> </snip>
>>
>> It's not clear to me that *not* minting media types *requires*
>> content/vocabulary negotiation. why have you chosen to explore these
>> to things in this related way?
>
> AFAIU Jorn (thinks he) needs different (sort of distinct) formats for
different consumers. When shoving both variants in a single host media type he
(thinks he) needs a means to negotiate between them based on the consumer.
>
> Jan
>
>
>
>>
>> mca
>> http://amundsen.com/blog/
>> http://twitter.com@mamund
>> http://mamund.com/foaf.rdf#me
>>
>> On Tue, Dec 27, 2011 at 10:45, Jan Algermissen
>> <jan.algermissen@...> wrote:
>> >
>> > On Dec 27, 2011, at 2:28 PM, Jorn Wildt wrote:
>> >>
>> >> Well, the examples are fictive from the start, so I cannot give that. As I
said, I am exploring the consequences of *not* minting new media types and
wondering how one would then do content/vocabulary negotiation.
>> >
>> > Ah, ok. BTW, you name one reason here, how non-specific media types+link
rels and friends take away control that Web arch actually intends to give you).
>> >
>> > Besides Accept-Features you could do sth. like this:
>> >
>> > GET /orders/1
>> > Accept: application/xhtml;profile=us-order
>> >
>> > 200 Ok
>> > Content-Type: application/xhtml
>> >
>> > However, I am not a fan of this because you loose visibility (media type
parameters other than 'q' are opaque to conneg) and you also do not know which
intermediary will silently strip the param (which it may).
>> >
>> > I also think you simply end up creating the bloat you are trying to avoid
in another place (the profile or feature tag).
>> >
>> > My advice remains: mint a media type, make it flexible enough to
incorporate whatever variations you might have and have the clients  deal with
picking the stuff they want.
>> >
>> > Jan
>> >
>> > P.S. You can also do Conneg on User-Agent but I have not yet made up my
mind whether that is a good idea.
>> >
>> >
>> >
>> >
>> >>
>> >> /Jørn
>> >>
>> >>
>> >
>> >
>> >
>> > ------------------------------------
>> >
>> > Yahoo! Groups Links
>> >
>> >
>> >
>>
>

> Jorn: you are contemplating a single media-type w/ multiple negotiable
> "formats"? is that right?

Yup. But read "Format" as "Vocabulary" or "encoding-in-existing-media-type" and
see my answer in http://tech.groups.yahoo.com/group/rest-discuss/message/18172

/Jørn

> It's not clear to me that *not* minting media types *requires*
> content/vocabulary negotiation.

It does not *require*. That's not what I am saying. Lets take it from the
beginning:

1) Assume minting new media types is a no-go. Lets encode the domain data in
HTML (or HAL) - a well known media format with built-in hypermedia controls.
(You were actually the one that got me started on this in
http://tech.groups.yahoo.com/group/rest-discuss/message/18126 with the comment
"and i think someone kicks a cat, too [when a new media type is created]" :-)

2) Now we need to embed a sales order or a case file or some other domain
specific data in the existing media type. Unfortunately we need to support
different vocabularies: the US vocabulary, the European Union vocabulary (both
fictive), some subset of UBL or the Good Relations vocabulary(*)

3) How does the client now inform the server of which vocabulary it understands?
The client can ask for text/html - but where should it put the
"and-please-serve-it-as-good-relations"-requirement?

As always - thanks for taking the time to discuss this.

/Jørn

(*) Never mind what exactly it is. The point is that we could have many
different ways of embedding the same data in the same media type.

Let me just give another example to show that this is not about XML alone:

1) Assume we have a resource with a sales order.

2) The client wants the sales order as a spreadsheet so it GETs it with accept
header "application/vnd.ms-excel".

3) But we have many different variations of the spreadsheet, so how does the
client inform the server of what variation it wants? The media type will always
be "application/vnd.ms-excel" no matter what, so we cannot change/switch on
that.

4) Exactly the same argument goes for representing the sales order in HTML, HAL,
and, well, even as a PDF or an image!

I guess it boils down to a question of what kind of variations we need. Let me
give some examples:

A) Different languages (english, turkish, what-ever). For this we can use the
HTTP header Accept-Language.

B) Different content (with or without summaries, full address, detailed
information etc.). In this case I would say we declare them as different
resources and need different URIs, for instance with a "?format=xxx" parameter.

C) Different layout but with the same content. For instance a new version of the
spreadsheet with the same data but in different cells. Typically we would mint a
new version of the media type - but that certainly doesn't make sense for a
spreadsheet!

/Jørn

> > Even if you buy into the "new media types are evil" meme (which
> I don't), what's wrong with a content type of
> "application/vnd.ms-excel;vocabulary+hal"?

Is that doable? It certainly looks like a good solution - but is it generally
accepted (a standard) that "application/vnd.ms-excel;vocabulary+hal" is the same
as "application/vnd.ms-excel" when it comes to parsing the content? Will for
instance Microsoft Excel open up from my browser if I clicked on a link the
returned "application/vnd.ms-excel;vocabulary+hal"?

/Jørn

----- Original Message -----

From: Peter Williams

To: rest-discuss@yahoogroups.com

Sent: Wednesday, December 28, 2011 8:18 PM

Subject: Re: [rest-discuss] Re: Different vocabularies, same media type

 

On Wed, Dec 28, 2011 at 11:19 AM, mike amundsen <mamund@...> wrote:

Jorn:

i must assume (since it's not clear in your messages) that this "single media type, multiple vocabularies" problem means:

- you decided to use only one media type

- you decided to map your problem domain details to this media type multiple ways (via these "vocabularies")

- you actually _need_ to do it this way.

first, "vocabularies" is rather vague to me. you name a few (some made up for the case of the discussion), but provide no examples. it is not clear to me how you plan to express the same problem domain information for the same resource using different "vocabularies." in fact, i doubt this scenario is practical in a live system. IOW, i doubt you can successfully create varying representations on the same resource expressing the same problem domain data using different "vocabularies." 

I am not sure if these are exactly what Jorn meant but some scenarios i have been considering are:

The overlap between the Dublin Core and FOAF vocabularies pretty significant for the HTML+RDFa scenario. Some clients will prefer FOAF terms, others will prefer DC. With RDFa you could annotate using both vocabularies. OTOH, it seems like it would be nice for the client to be able to say "i need FOAF flavored HTML+RDFa" so that the server could say "Not Acceptable" if it only knows how to speak DC (or doesn't annotate using RDFa at all).

If you use the semantics of vanilla HTML, rather than RDFa, there are usually several reasonable ways to express domain concepts in HTML. More than once i have switched from rendering data into definition lists to rendering very similar data into tables. It is challenging to write automated clients that would be able to handle such a change seamlessly. (Humans on the other hand couldn't care less.) It seems like it would be nice for the client to be able surface it's requirements to the server.

If the whole world always agreed on how to describe problem domains, and never made mistakes, then generic media types would be very compelling. I fear that is not the world i live in, though. As Andrew Tanenbaun said, "the nice thing about standards is that you have so many to choose from". And that assumes there are any standards at all, which is a pretty big assumption for many problem domains.

Peter

http://barelyenough.org

 

> it is not clear to me how you plan to express the same problem domain
> information for the same resource using different "vocabularies."

Well, first of all Peter gave a perfect example with a choice between Dublin
Core and FOAF embeded in HTML.

I can give another example from my own job: we are working with a case
management system. A case file can be represented in HTML in various
(realistic) ways:

1) Using micro formats

2) Using RDFa

Furthermore, we can either choose to name the case file properties using a
Nordic standard, which really doesn't fit our data model very well, or we
can name the properties using some other (non-)standard that fits the data
model a lot better.

All in all we have a minimum of four different ways of expressing the
content of a case file using HTML. And thats not counting the gazillion
different ways to express stuff in micro formats.

Now I want the client to be able to say "I understand HTML and please serve
it as a micro format using Nordic standard names".

/Jørn

----- Original Message -----
From: mike amundsen
To: Erik Mogensen
Cc: Jorn Wildt ; rest-discuss@yahoogroups.com
Sent: Wednesday, December 28, 2011 7:19 PM
Subject: Re: [rest-discuss] Re: Different vocabularies, same media type


Jorn:


i must assume (since it's not clear in your messages) that this "single
media type, multiple vocabularies" problem means:
- you decided to use only one media type
- you decided to map your problem domain details to this media type multiple
ways (via these "vocabularies")
- you actually _need_ to do it this way.


first, "vocabularies" is rather vague to me. you name a few (some made up
for the case of the discussion), but provide no examples. it is not clear to
me how you plan to express the same problem domain information for the same
resource using different "vocabularies." in fact, i doubt this scenario is
practical in a live system. IOW, i doubt you can successfully create varying
representations on the same resource expressing the same problem domain data
using different "vocabularies."


instead, i suspect that, when using these "vocabularies" to express problem
domain specifics, you'll find that the representations vary widely enough
that they are not (practically speaking) the same _resource_ at all. i
encourage you to prove me wrong on this point by providing some clear
examples.


second, it sounds (from you responses here) that you imagine multiple
clients out there that all understand the same media type, but don't share
an understanding of the same vocabularies. you also mention the notion of
"negotiating" for vocabularies between client and server. again, i can't
conjure up real-life examples of this (feel free to point to some).


i think you are positing scenarios that while possible, are unlikely and/or
sub-optimal. i think it likely likely that you will encounter clients that
differ in the way domain specifics are represented. i those cases, i suggest
the most effective way to do that is to provide unique addresses. this is
especially true (IMO) when the representation includes "actionable"
hypermedia controls upon which the client is expected to act.


in my experience, attempts to do "multiple things" while using the same URI
are not often successful; esp. when the client is expected to recognize,
parse, and act on the response representation.

mca
http://amundsen.com/blog/
http://twitter.com@mamund
http://mamund.com/foaf.rdf#me





On Wed, Dec 28, 2011 at 09:12, Erik Mogensen <erik@...> wrote:



On Wed, Dec 28, 2011 at 8:28 AM, Jorn Wildt <jw@...> wrote:

1) Assume we have a resource with a sales order.
[...]
I guess it boils down to a question of what kind of variations we need. Let
me give some examples:

[...]
C) Different layout but with the same content. For instance a new version of
the spreadsheet with the same data but in different cells. Typically we
would mint a new version of the media type - but that certainly doesn't make
sense for a spreadsheet!


If you have different layouts (or even just different styles) of cells in
two spreadsheets, I would not give them the same URI.


A URI may identify one and only one resource, but a resource may be
identified by any number of URIs. That's a fact of life; one of the a trade
offs of combining the network address with the resource identifier.


IMHO that would go for the XML vocabularies too: The "EU sales order" and
the "US sales order" (or whatever the hypothetical case was) don't _have_ to
have the same URI, even though they come from the same rows in the same
database tables.  Solving the problem of linking/navigating to the "right"
resource is a lot easier; hypermedia. Clients can't depend on all players
always using the one true URI of any resource to identify it; witness
tinyurl.com and derivatives.


Different layout with the same content... Heard that before:  WML. That
worked out well? ;-)  How do sites really handle it?  Usually using the same
media types, but using "m.example.com" subdomains, i.e. different URIs for
the same "resource".
--
-mogsie-

There has been lots of valuable feed back on this thread. Thanks a lot to
everybody who has contributed! Hopefully you now understand the problem :-)

The suggested solutions has been:

1) Mint a new media type.

Apparently there are two different schools here. Some say, yes, go for a new
media type. Some say, no don't. And there is no agreement upon which is best.
See http://tech.groups.yahoo.com/group/rest-discuss/message/18183 for a
discussion of this.

2) Use different URIs for the different vocabularies.

This seems like an easy and well understood solution. As Mike puts it: "in my
experience, attempts to do "multiple things" while using the same URI are not
often successful" (meaning, "go for multiple URIs").

3) Switch on a media type parameter in the accept header (as for instance
"application/xhtml+xml;profile=xxx").

To me this seems like the most elegant solution - if it works. Some people argue
that the ";profile=xxx" parameter may get stripped by intermediaries in the
network. It has the advantages of minting a new media type, but none of the
drawbacks since it is still a well known media type (if this is the right
interpretation of the syntax!)

4) Switch on other headers like for instance the user-agent.

Not a generally used solution.

5) Use all vocabularies in the same document.

To me this seems too clumsy.

/Jørn

Jorn:

i think you did a good job of summing up the opinions presented here.

since i don't run into this often in my current work (using a single
media type and multiple "vocabularies" to represent the same problem
domain details), i am most interested in the solution you end up
creating. hopefully, you will be able to share not just the outcome
("we decided to go with 'x' approach and here's why...") but also the
process ("at first we did y, then discovered it didn't work for z, so
we adjusted to x...").

i think your adventure would be very interesting and i suspect many
others would, too.

thanks.

mca
http://amundsen.com/blog/
http://twitter.com@mamund
http://mamund.com/foaf.rdf#me




On Wed, Dec 28, 2011 at 16:22, Jorn Wildt <jw@...> wrote:
> There has been lots of valuable feed back on this thread. Thanks a lot to
everybody who has contributed! Hopefully you now understand the problem :-)
>
> The suggested solutions has been:
>
> 1) Mint a new media type.
>
> Apparently there are two different schools here. Some say, yes, go for a new
media type. Some say, no don't. And there is no agreement upon which is best.
See http://tech.groups.yahoo.com/group/rest-discuss/message/18183 for a
discussion of this.
>
> 2) Use different URIs for the different vocabularies.
>
> This seems like an easy and well understood solution. As Mike puts it: "in my
experience, attempts to do "multiple things" while using the same URI are not
often successful" (meaning, "go for multiple URIs").
>
> 3) Switch on a media type parameter in the accept header (as for instance
"application/xhtml+xml;profile=xxx").
>
> To me this seems like the most elegant solution - if it works. Some people
argue that the ";profile=xxx" parameter may get stripped by intermediaries in
the network. It has the advantages of minting a new media type, but none of the
drawbacks since it is still a well known media type (if this is the right
interpretation of the syntax!)
>
> 4) Switch on other headers like for instance the user-agent.
>
> Not a generally used solution.
>
> 5) Use all vocabularies in the same document.
>
> To me this seems too clumsy.
>
> /Jørn
>
>
>
>
> ------------------------------------
>
> Yahoo! Groups Links
>
>
>

Hi,

maybe the new HTML Data Guide draft will also give some interesting
impressions on that topic, see

https://dvcs.w3.org/hg/htmldata/raw-file/default/html-data-guide/index.html

Cheers,


Bo


On 12/28/2011 11:05 PM, mike amundsen wrote:
> Jorn:
>
> i think you did a good job of summing up the opinions presented here.
>
> since i don't run into this often in my current work (using a single
> media type and multiple "vocabularies" to represent the same problem
> domain details), i am most interested in the solution you end up
> creating. hopefully, you will be able to share not just the outcome
> ("we decided to go with 'x' approach and here's why...") but also the
> process ("at first we did y, then discovered it didn't work for z, so
> we adjusted to x...").
>
> i think your adventure would be very interesting and i suspect many
> others would, too.
>
> thanks.
>
> mca
> http://amundsen.com/blog/
> http://twitter.com@mamund
> http://mamund.com/foaf.rdf#me
>
> On Wed, Dec 28, 2011 at 16:22, Jorn Wildt <jw@...
> <mailto:jw%40fjeldgruppen.dk>> wrote:
>  > There has been lots of valuable feed back on this thread. Thanks a
> lot to everybody who has contributed! Hopefully you now understand the
> problem :-)
>  >
>  > The suggested solutions has been:
>  >
>  > 1) Mint a new media type.
>  >
>  > Apparently there are two different schools here. Some say, yes, go
> for a new media type. Some say, no don't. And there is no agreement upon
> which is best. See
> http://tech.groups.yahoo.com/group/rest-discuss/message/18183 for a
> discussion of this.
>  >
>  > 2) Use different URIs for the different vocabularies.
>  >
>  > This seems like an easy and well understood solution. As Mike puts
> it: "in my experience, attempts to do "multiple things" while using the
> same URI are not often successful" (meaning, "go for multiple URIs").
>  >
>  > 3) Switch on a media type parameter in the accept header (as for
> instance "application/xhtml+xml;profile=xxx").
>  >
>  > To me this seems like the most elegant solution - if it works. Some
> people argue that the ";profile=xxx" parameter may get stripped by
> intermediaries in the network. It has the advantages of minting a new
> media type, but none of the drawbacks since it is still a well known
> media type (if this is the right interpretation of the syntax!)
>  >
>  > 4) Switch on other headers like for instance the user-agent.
>  >
>  > Not a generally used solution.
>  >
>  > 5) Use all vocabularies in the same document.
>  >
>  > To me this seems too clumsy.
>  >
>  > /Jørn

On Tue, Dec 27, 2011 at 3:51 PM, mike amundsen <mamund@...> wrote:
> <snip>
> I am exploring the consequences of *not* minting new media types and
> wondering how one would then do content/vocabulary negotiation.
> </snip>
>
> It's not clear to me that *not* minting media types *requires*
> content/vocabulary negotiation. why have you chosen to explore these
> to things in this related way?
>

+1

This assumption seems to be the crux of the problem

> you could do sth. like this:
>
> GET /orders/1
> Accept: application/xhtml;profile=us-order
>
> 200 Ok
> Content-Type: application/xhtml
>
> However, I am not a fan of this because you loose visibility (media type
parameters other than 'q' are opaque to conneg) and you also do not know which
intermediary will silently strip the param (which it may).

That is although what I would consider a solution that fits exactly my
requirements. Can you explain what the parameter can get stripped (or share a
link)?

Thanks, Jørn

Reading up on the profile attribute (http://www.ietf.org/rfc/rfc3236.txt). Seems
like a good choice for the purpose of defining the vocabulary/encoding used to
embed data in XHTML.

The spec says though "It is primarily targeted for use on the network by proxies
in the HTTP chain that manipulate data formats (such as transcoders).". My
application is not a proxy - so maybe this is what is meant by "you also do not
know which intermediary will silently strip the param (which it may)"?

/Jørn

Jan Algermissen wrote:
>
> Applying REST to enterprise IT problems does not mean tweaking REST,
> it means changing your view of the problem.
>

+5

-Eric

> > Applying REST to enterprise IT problems does not mean tweaking REST,
> > it means changing your view of the problem.
>
> +5

And thanks a lot for helping me/the community do that :-)

/Jørn