As a subscriber of this 'meme' Craig mentioned, I'll give a few of the

reasons using a generic media type is the better option:



- they avoid you having to reinvent the wheel (i.e. linking to and

embedding of resources)



- they bring existing client/server tooling that can be re-used in

your application



- as further tooling is developed and improved over time your

application will benefit



- they avoid the temptation to type resources via the media type identifier



- they establish a ubiquitous interface against which more

sophisticated clients/servers/intermediary mechanisms can emerge





Is someone able to put together a similar list for the "new media

types are awesome" meme?



Cheers,

Mike

On Dec 28, 2011, at 10:44 AM, Mike Kelly wrote:



> As a subscriber of this 'meme' Craig mentioned, I'll give a few of the

> reasons using a generic media type is the better option:



You sure meant to say that this is *your opinion*, eh?



>

> - they avoid you having to reinvent the wheel (i.e. linking to and

> embedding of resources)

>

> - they bring existing client/server tooling that can be re-used in

> your application

>

> - as further tooling is developed and improved over time your

> application will benefit



You get all of the above by using existing syntaxes in new, specific media

types.



>

> - they avoid the temptation to type resources via the media type identifier



That 'temptation' can better be cured by educating people about good media type

design.



>

> - they establish a ubiquitous interface against which more

> sophisticated clients/servers/intermediary mechanisms can emerge



We already have that interface: HTTPs uniform interface. Adding yet another

level of uniformness just moves the specifics elsewhere. It does not change the

fact that you need specifics.



Jan



>

> Is someone able to put together a similar list for the "new media

> types are awesome" meme?

>

> Cheers,

> Mike

>

On Wed, Dec 28, 2011 at 10:28 AM, Jan Algermissen

<jan.algermissen@...> wrote:

> We already have that interface: HTTPs uniform interface. Adding yet another

level of uniformness just moves the specifics elsewhere. It does not change the

fact that you need specifics.



That's generally true for M2M at this point.



Human beings, however, can adapt to new HTML interfaces because they

are self-describing.



--

Benjamin Hawkes-Lewis

On Dec 28, 2011, at 11:42 AM, Benjamin Hawkes-Lewis wrote:



> On Wed, Dec 28, 2011 at 10:28 AM, Jan Algermissen

> <jan.algermissen@...> wrote:

>> We already have that interface: HTTPs uniform interface. Adding yet another

level of uniformness just moves the specifics elsewhere. It does not change the

fact that you need specifics.

>

> That's generally true for M2M at this point.

>

> Human beings, however, can adapt to new HTML interfaces because they

> are self-describing.



I tend to avoid that distinction altogether. User agents are components that act

on behalf of some user. User agents execute any number of requests automatically

(depending on their implementation and configuration) until they reach a steady

state. At that point they hand back use case control to the user (the primary

actor in use case speak).



It does not really matter, whether the automatic steps are image or style sheet

retrieval, form submissions, following redirects or comparing product prices

from several shops and submitting an order for the cheapest offer.



Either way, the use agent will end up in a steady state (be that an Ok state or

Error state) leaving the user to figure out how to proceed with its intent given

the presented state.



A browser is as much an M2M thing as a bidding agent. The browser simply hand

control to the primary actor more often.



Jan



>

> --

> Benjamin Hawkes-Lewis

On Wed, Dec 28, 2011 at 3:44 PM, Jan Algermissen

<jan.algermissen@...> wrote:

>

> On Dec 28, 2011, at 11:42 AM, Benjamin Hawkes-Lewis wrote:

>

>> On Wed, Dec 28, 2011 at 10:28 AM, Jan Algermissen

>> <jan.algermissen@...> wrote:

>>> We already have that interface: HTTPs uniform interface. Adding yet another

level of uniformness just moves the specifics elsewhere. It does not change the

fact that you need specifics.

>>

>> That's generally true for M2M at this point.

>>

>> Human beings, however, can adapt to new HTML interfaces because they

>> are self-describing.

>

> I tend to avoid that distinction altogether.



[snip]



> The browser simply hand control to the primary actor more often.



You can re-express what I said as: "HTML allows easier adaption by

naive primary actors than newly minted media types", and my point

remains the same.



--

Benjamin Hawkes-Lewis

I can think of three key reasons to consider creating new media types:



1 - improve access to protocol-level details available within the message.

For example, HTML lacks support for accessing PUT, DELETE, PATCH, and

a number of HTTP Headers.



2 - improve the affordances provided by the media type.

For example, Atom lacks the affordance for expressing ad-hoc queries

(i.e. HTML.FORM@method="get") in representations.



3 - improve the mapping between the problem domain and the message.

For example, while implementing a voice response system using HTML is

quite possible, the VoiceXML media type offers a more direct mapping

between the messages and the problem domain.





mca

http://amundsen.com/blog/

http://twitter.com@mamund

http://mamund.com/foaf.rdf#me









On Wed, Dec 28, 2011 at 11:06, Benjamin Hawkes-Lewis

<bhawkeslewis@...> wrote:

> On Wed, Dec 28, 2011 at 3:44 PM, Jan Algermissen

> <jan.algermissen@...> wrote:

>>

>> On Dec 28, 2011, at 11:42 AM, Benjamin Hawkes-Lewis wrote:

>>

>>> On Wed, Dec 28, 2011 at 10:28 AM, Jan Algermissen

>>> <jan.algermissen@...> wrote:

>>>> We already have that interface: HTTPs uniform interface. Adding yet another

level of uniformness just moves the specifics elsewhere. It does not change the

fact that you need specifics.

>>>

>>> That's generally true for M2M at this point.

>>>

>>> Human beings, however, can adapt to new HTML interfaces because they

>>> are self-describing.

>>

>> I tend to avoid that distinction altogether.

>

> [snip]

>

>> The browser simply hand control to the primary actor more often.

>

> You can re-express what I said as: "HTML allows easier adaption by

> naive primary actors than newly minted media types", and my point

> remains the same.

>

> --

> Benjamin Hawkes-Lewis

>

>

> ------------------------------------

>

> Yahoo! Groups Links

>

>

>

in the past, i've handled changes to protocol-level items or new

affordances by creating new media type definitions.



i will note, however, that one of the goals of XHTML 2.0[1] was to

create a core media type w/ optional "modules" for various other

"features." this never gained traction with browser vendors, tho.



> Not sure about this one - what is the benefit of this? more concise

representations?

the primary benefit is to reduce the abstraction layers between the

problem domain and the message:

<p class="invoice">...</p>

VS

<invoice>...</invoice>



FWIW, i usually handle problem domain mappings via a "profile" against

an existing media type (i.e. XHTML). sometimes, this does not work out

(for various reasons) and i author a new media type instead.



[1] http://www.w3.org/TR/xhtml2/xhtml2-doctype.html#s_doctype



On Wed, Dec 28, 2011 at 12:13, Mike Kelly <mike@...> wrote:

>

>

> On Wed, Dec 28, 2011 at 4:55 PM, mike amundsen <mamund@...> wrote:

>>

>>

>>

>> I can think of three key reasons to consider creating new media types:

>>

>> 1 - improve access to protocol-level details available within the message.

>> For example, HTML lacks support for accessing PUT, DELETE, PATCH, and

>> a number of HTTP Headers.

>

>

> Out of interest - do you would prefer a new media type identifier over

> profiles/conventions and code on demand?



in the past, i've handled changes to protocol-level items or new

affordances by creating new media type definitions.



i will note, however, that one of the goals of XHTML 2.0[1] was to

create a code media type w/ "plug-ins" for various other "features."

this never gained traction.



[1] http://www.w3.org/TR/xhtml2/xhtml2-doctype.html#s_doctype

>

> Either way, the point is understood. It's interesting that, despite these

> shortcomings, HTML's persisted that way for as long as it has. I think that

> speaks to the value of ubiquity in a media type.

>

>>

>> 2 - improve the affordances provided by the media type.

>> For example, Atom lacks the affordance for expressing ad-hoc queries

>> (i.e. HTML.FORM@method="get") in representations.

>>

>

> Agree, I'd also add constraints as well as affordances.

>

> Fwiw, this is the plan for introducing form-like controls to HAL - it will

> be a separate media type which extends it, dubbed SHAL.

>

>>

>> 3 - improve the mapping between the problem domain and the message.

>> For example, while implementing a voice response system using HTML is

>> quite possible, the VoiceXML media type offers a more direct mapping

>> between the messages and the problem domain.

>>

>







>

> Cheers,

> Mike

> > For example, Atom lacks the affordance for expressing ad-hoc queries

> > (i.e. HTML.FORM@method="get") in representations.

> Fwiw, this is the plan for introducing form-like controls to HAL - it will

> be a separate media type which extends it, dubbed SHAL.



Which is a rather interesting point ... let me play the devil's advocate ...

proponents of "do not mint new media types" would argue that this is exactly

why you should stay with the existing media types. Now you spend time and

effort in re-defining what a link is and what a form is - hypermedia

controls that are already well known in (X)HTML.



You could as well have spent the effort on defining a standard generic way

to encode domain data in XHTML such that it would be easy to parse in M2M

scenarios. It could be RDFa or something equivalent to HAL - albeit in

XHTML:



   <div class="resource">

     <a href="...">...</a>

     <a href="...">...</a>

     <span class="Name">THansen</span>

     <span class="Age">17</span>

     <form method="...">...</form>

     <div class="resource">

       ...

     </div>

   </div>



/Jørn

FWIW, there are times when i am constrained to only use Atom/AtomPub,

but still need to support ad-hoc queries (HTML.FORM@method="get")

and/or write operations with inline arguments

(HTML.FORM@method="post").



in these cases, i usually use the Atom message as a "wrapper" for an

embedded payload based on XHTML. the representations are simply

slip-streamed into the atom:content element and the client is "taught"

to recognize, parse, and activate hypermedia controls within the

atom:content element of an Atom response.



it's a hack, but it works well.



mca

http://amundsen.com/blog/

http://twitter.com@mamund

http://mamund.com/foaf.rdf#me









On Wed, Dec 28, 2011 at 17:52, Jørn Wildt <jw@...> wrote:

>> > For example, Atom lacks the affordance for expressing ad-hoc queries

>> > (i.e. HTML.FORM@method="get") in representations.

>> Fwiw, this is the plan for introducing form-like controls to HAL - it will

>> be a separate media type which extends it, dubbed SHAL.

>

>

> Which is a rather interesting point ... let me play the devil's advocate ...

> proponents of "do not mint new media types" would argue that this is exactly

> why you should stay with the existing media types. Now you spend time and

> effort in re-defining what a link is and what a form is - hypermedia

> controls that are already well known in (X)HTML.

>

> You could as well have spent the effort on defining a standard generic way

> to encode domain data in XHTML such that it would be easy to parse in M2M

> scenarios. It could be RDFa or something equivalent to HAL - albeit in

> XHTML:

>

>  <div class="resource">

>   <a href="...">...</a>

>   <a href="...">...</a>

>   <span class="Name">THansen</span>

>   <span class="Age">17</span>

>   <form method="...">...</form>

>   <div class="resource">

>     ...

>   </div>

>  </div>

>

> /Jørn

>

On Wed, Dec 28, 2011 at 10:28 AM, Jan Algermissen

<jan.algermissen@...> wrote:

>

> On Dec 28, 2011, at 10:44 AM, Mike Kelly wrote:

>

>>

>> - they avoid you having to reinvent the wheel (i.e. linking to and

>> embedding of resources)

>>

>> - they bring existing client/server tooling that can be re-used in

>> your application

>>

>> - as further tooling is developed and improved over time your

>> application will benefit

>

> You get all of the above by using existing syntaxes in new, specific media

types.

>



Sort of.. just in a more convoluted, less convenient way. You as the

server need to spend the effort composing your new type, and any

clients then consuming that media type would need to unravel your

composition at the other end - all of this is necessary before

actually tackling the application. Whereas a complete generic type

designed for the purpose of exposing a REST API will save both server

and clients that kind of bother, and afaict that can only be a good

thing!



>>

>> - they avoid the temptation to type resources via the media type identifier

>

> That 'temptation' can better be cured by educating people about good media

type design.

>



“Design depends largely on constraints.”

-- Charles Eames



>>

>> - they establish a ubiquitous interface against which more

>> sophisticated clients/servers/intermediary mechanisms can emerge

>

> We already have that interface: HTTPs uniform interface. Adding yet another

level of uniformness just moves the specifics elsewhere. It does not change the

fact that you need specifics.

>



This isn't the case for HTML, why should m2m be different?



By specifics I assume you mean the actual application semantics?



In HAL's case, the application semantics are moved (on purpose) into

the link relations. This means applications exposed with HAL must be

defined/governed in terms of link relations, the key benefits of this

are covered in Mark Nottingham's post "Web API Versioning

Smackdown"[1].



[1] http://www.mnot.net/blog/2011/10/25/web_api_versioning_smackdown

On Wed, Dec 28, 2011 at 6:51 PM, Erik Mogensen <erik@...> wrote:

> I think we need a discussion / definition on what actually a "specific" media

type actually is before we discuss its merits.



I fully agree that it would be good to clarify what is meant by a media type.



To me it is a representation format type, not a conceptual data type.

The HTTP spec, section 3.7 says:



"HTTP uses Internet Media Types [17] in the Content-Type (section

14.17) and Accept (section 14.1) header fields in order to provide

open and extensible data typing and type negotiation."



An Internet Media Type is a file format type or representation format

type. It is *not* a conceptual or business data type in the sense of

an INTEGER, STRING, HEALTHCARE_RECORD or PURCHASE_ORDER. A format type

tells a client how to parse an entity body, not how to interpret it.

Maybe "Content-Type" should have been named "Content-Format" instead.



With image data the distinction becomes clearer; we can use different

representation format types like jpg, gif or png but, the actual

conceptual interpretation of the image, ie. "what it is an image of",

is out-of bounds for HTTP.



Of course at some level any client-server system has to agree on the

core business concepts that will be represented by some business

specific data type. However at the interface and and representation

format level I want to be able to use standard tools and not to risk

interfering with the nice properties of HTTP. I think conceptual or

business data type information, ie. how an entity body should be

interpreted, should be handled as out-of band information of the

current version of HTTP.



Maybe some syntax convention could be found for combining

representation format type *and* conceptual/business data type

information in the content-type header, eg

"application/json&purchase-order" or else a new HTTP header

"Concept-Type" could be introduced that indicates the

conceptual/business data type of the entity body, eg "Concept-Type:

purchase-order". This would at least give HTTP clients a *hint* of how

to interpret the entity body and "Concept-Type" names could also be

used in hyperlinks to give clients hints about the interpretation of a

resource before having to dereference the hyperlink to that resource.



Having said that, I would be satisifed with one single new media type;

one that combines JSON:s simple expressiveness with native support for

hyperlinks! :-)



/Paul



--

Paul Cohen

www.seibostudios.se

mobile: +46 730 787 035

e-mail: paul.cohen@...

hello.



On 2011-12-28 16:21 , Paul Cohen wrote:

> Maybe some syntax convention could be found for combining

> representation format type *and* conceptual/business data type

> information in the content-type header, eg

> "application/json&purchase-order" or else a new HTTP header

> "Concept-Type" could be introduced that indicates the

> conceptual/business data type of the entity body, eg "Concept-Type:

> purchase-order". This would at least give HTTP clients a *hint* of how

> to interpret the entity body and "Concept-Type" names could also be

> used in hyperlinks to give clients hints about the interpretation of a

> resource before having to dereference the hyperlink to that resource.



that would make a lot of sense, because only then could you cleanly

communicate that you can, for example, provide the same conceptual

information in two different serializations, such as XML and JSON.

lumping the concept type into the serialization format is a hack, which

occasionally may be useful, really mixes two issues which should be

treated separately (and in many cases, the concept type might not even

be necessary, such as for the web's HTML pages where "page concepts"

sometimes are inferred by crawlers/indexers, but are never tagged

explicitly). the "application/...+xml" convention really is nothing but

engineering around that problem, using a convention that is not even

consistent across media types and only creates the illusion that you're

actually separating the data model and the serialization format.



cheers,



dret.



--

erik wilde | mailto:dret@...  -  tel:+1-510-2061079 |

             | UC Berkeley  -  School of Information (ISchool) |

             | http://dret.net/netdret http://twitter.com/dret |

the notion of expressing a problem domain independent of the message

format itself (via vocabularies, ontologies, etc) in a way that

enables M2M communication and collaboration is a compelling one but,

IMO, not easy to accomplish. i've taken a couple stabs at it over the

last year and have yet to find my efforts successful.



even i cases where i think it may be possible to create a "shared

understanding" of the problem domain, i have yet to find a way to

successfully  map that understanding onto a media type in a way that

is consistently consumable by generic clients. the idea of being able

to map problem domain descriptions to *multiple* media types is

something i've not seen yet anywhere (feel free to point me to

examples anyone knows about).



it is my suspicion that the work of SemWeb and REST have the potential

to meet in a way that comes close to this goal; the ability enable M2M

interactions to consistently share understanding about a problem

domain independent of the format of the shared understanding of the

message format.



if anyone is working on such a project, or knows of one, please let me know.



mca

http://amundsen.com/blog/

http://twitter.com@mamund

http://mamund.com/foaf.rdf#me









On Wed, Dec 28, 2011 at 19:51, Erik Wilde <dret@...> wrote:

> hello.

>

> On 2011-12-28 16:21 , Paul Cohen wrote:

>> Maybe some syntax convention could be found for combining

>> representation format type *and* conceptual/business data type

>> information in the content-type header, eg

>> "application/json&purchase-order" or else a new HTTP header

>> "Concept-Type" could be introduced that indicates the

>> conceptual/business data type of the entity body, eg "Concept-Type:

>> purchase-order". This would at least give HTTP clients a *hint* of how

>> to interpret the entity body and "Concept-Type" names could also be

>> used in hyperlinks to give clients hints about the interpretation of a

>> resource before having to dereference the hyperlink to that resource.

>

> that would make a lot of sense, because only then could you cleanly

> communicate that you can, for example, provide the same conceptual

> information in two different serializations, such as XML and JSON.

> lumping the concept type into the serialization format is a hack, which

> occasionally may be useful, really mixes two issues which should be

> treated separately (and in many cases, the concept type might not even

> be necessary, such as for the web's HTML pages where "page concepts"

> sometimes are inferred by crawlers/indexers, but are never tagged

> explicitly). the "application/...+xml" convention really is nothing but

> engineering around that problem, using a convention that is not even

> consistent across media types and only creates the illusion that you're

> actually separating the data model and the serialization format.

>

> cheers,

>

> dret.

>

> --

> erik wilde | mailto:dret@...  -  tel:+1-510-2061079 |

>            | UC Berkeley  -  School of Information (ISchool) |

>            | http://dret.net/netdret http://twitter.com/dret |

>

>

> ------------------------------------

>

> Yahoo! Groups Links

>

>

>

hello mike.



On 2011-12-28 18:45 , mike amundsen wrote:

> even i cases where i think it may be possible to create a "shared

> understanding" of the problem domain, i have yet to find a way to

> successfully  map that understanding onto a media type in a way that

> is consistently consumable by generic clients. the idea of being able

> to map problem domain descriptions to *multiple* media types is

> something i've not seen yet anywhere (feel free to point me to

> examples anyone knows about).



skipping over the other interesting questions you were asking: just look

at mobile web sites and how web servers adapt to mapping the same

problem domain ("getting the web site contents to a browser") to

different media types, sometimes just as variations of text/html, but

sometimes also as text/vnd.wap.wml, making sure that WAP browsers can be

used as well. some web pages even map their problem domain to

application/pdf, allowing paginated paper-oriented clients to understand it.



another example from the m2m world is any service that provides JSON and

XML access. sometimes these may be functionally different, because of

different assumptions about the "typical client" for that media types,

but often they are really just different representations, and RDF often

is thrown into the mix as well (some services even throw in CSV for

spreadsheet aficionados, but that often loses some of the expressiveness

of the domain model because of its simplicity).



cheers,



dret.





--

erik wilde | mailto:dret@...  -  tel:+1-510-2061079 |

             | UC Berkeley  -  School of Information (ISchool) |

             | http://dret.net/netdret http://twitter.com/dret |

> it is my suspicion that the work of SemWeb and REST have the potential

> to meet in a way that comes close to this goal; the ability enable M2M

> interactions to consistently share understanding about a problem

> domain independent of the format of the shared understanding of the

> message format.



Yup. +1



/Jørn

Hi Mike,



On 12/29/2011 3:45 AM, mike amundsen wrote:

> the notion of expressing a problem domain independent of the message

> format itself (via vocabularies, ontologies, etc) in a way that

> enables M2M communication and collaboration is a compelling one but,

> IMO, not easy to accomplish. i've taken a couple stabs at it over the

> last year and have yet to find my efforts successful.

>

> even i cases where i think it may be possible to create a "shared

> understanding" of the problem domain, i have yet to find a way to

> successfully map that understanding onto a media type in a way that

> is consistently consumable by generic clients. the idea of being able

> to map problem domain descriptions to *multiple* media types is

> something i've not seen yet anywhere (feel free to point me to

> examples anyone knows about).

>

> it is my suspicion that the work of SemWeb and REST have the potential

> to meet in a way that comes close to this goal; the ability enable M2M

> interactions to consistently share understanding about a problem

> domain independent of the format of the shared understanding of the

> message format.

>

> if anyone is working on such a project, or knows of one, please let me know.



from my point of view, the answer still is the knowledge representation

language RDF (incl. (optionally) RDFS, OWL, ...), which can be

serialized into various representation formats, e.g., Turtle, RDFa,

RDF/JSON, RDF/XML (Microdata is a "yet not another"-approach with not

many improvements (from my POV)). (Of course,) The Hypermedia/HATEOAS

definitions must be part of the representation format media type.



(as some of you may remember ... :) ) I tried to discuss and investigate

the relation between Linked Data, Semantic Web technologies and REST for

a while (see, e.g., [1] and [2]).



Cheers,





Bo





[1]

http://answers.semanticweb.com/questions/2763/the-relation-of-linked-datasemanti\

c-web-to-rest

[2]

http://smiy.org/2011/02/17/a-generalisation-of-the-linked-data-publishing-guidel\

ine/

On Thursday, December 29, 2011 10:45 AM, mike amundsen wrote:

> it is my suspicion that the work of SemWeb and REST have the potential

> to meet in a way that comes close to this goal; the ability enable M2M

> interactions to consistently share understanding about a problem

> domain independent of the format of the shared understanding of the

> message format.

>

> if anyone is working on such a project, or knows of one, please let me

know.



Mike, I share your opinion. I think that Sematic Web technologies provide a

great potential to bring RESTful systems forward. Of course, it won't change

REST but augment it by a semantic layer on top of it.



I'm actively working on this, see http://bit.ly/seredasj,

http://bit.ly/sparql2rest or

http://www.json-ld.org/spec/latest/json-ld-syntax/





> the notion of expressing a problem domain independent of the message

> format itself (via vocabularies, ontologies, etc) in a way that

> enables M2M communication and collaboration is a compelling one but,

> IMO, not easy to accomplish. i've taken a couple stabs at it over the

> last year and have yet to find my efforts successful.



I would love to know more about your efforts..





--

Markus Lanthaler

@markuslanthaler

On Dec 29, 2011, at 1:21 AM, Paul Cohen wrote:



>  or else a new HTTP header

> "Concept-Type" could be introduced that indicates the

> conceptual/business data type of the entity body, eg "Concept-Type:

> purchase-order". This would at least give HTTP clients a *hint* of how

> to interpret the entity body



That 'hint' already exists and is called "Content-Type".



Jan

On Dec 29, 2011, at 8:19 AM, Jan Algermissen wrote:



>

> On Dec 29, 2011, at 1:21 AM, Paul Cohen wrote:

>

> > or else a new HTTP header

> > "Concept-Type" could be introduced that indicates the

> > conceptual/business data type of the entity body, eg "Concept-Type:

> > purchase-order". This would at least give HTTP clients a *hint* of how

> > to interpret the entity body

>

> That 'hint' already exists and is called "Content-Type".





Consider, for example, application/atom+xml. This media type has two root level

document types, feeds and entries. There is no need to distinguish between the

two at the Content-Type header level because the user agent simply reacts on

what it receives.



If you were doing procurement, some application/procurement media type would do.

There can be <offer>,<order>,<invoice>, <creditNote>,... in that media type

without any need for further hints than Content-Type: application/procurement.



Jan









>

> Jan

>

>

On Dec 29, 2011, at 9:39 AM, Craig McClanahan wrote:



> On Thu, Dec 29, 2011 at 12:11 AM, Jan Algermissen <jan.algermissen@...>

wrote:

>

> On Dec 29, 2011, at 8:19 AM, Jan Algermissen wrote:

>

> >

> > On Dec 29, 2011, at 1:21 AM, Paul Cohen wrote:

> >

> > > or else a new HTTP header

> > > "Concept-Type" could be introduced that indicates the

> > > conceptual/business data type of the entity body, eg "Concept-Type:

> > > purchase-order". This would at least give HTTP clients a *hint* of how

> > > to interpret the entity body

> >

> > That 'hint' already exists and is called "Content-Type".

>

>

> Consider, for example, application/atom+xml. This media type has two root

level document types, feeds and entries. There is no need to distinguish between

the two at the Content-Type header level because the user agent simply reacts on

what it receives.

>

> So, please explain for me again why application/atom+xml is better than

application/procurement for this?



What is 'this'?



Atom is only good for the specific kind of communication it is designed for - if

your intention is to do procurement, define a specific media type for the

communication of that 'domain'.





>

> Yes, I can understand (at a syntactic level) that I might receive a "link"

element with a "rel" value of "checkout" and a corresponding URL.  But what the

heck does a "rel" value of "checkout" *mean* in terms of what the client app

should do next?



The user agent needs to be hard-coded (or configured) to understand what to do

when it sees a rel="checkout". REST does not provide (and neither intends to do

so) a magic means of removing inherent requirements of communication.



>

> Not negotiating content types at the HTTP media type level means I just have

to negotiate them at some lower level (after I understand the syntax). That's

not an improvement in interop ... that's just sweeping an inconvenient problem

under the carpet.



Can you tell me who brought up the idea that REST user agents would suddenly

understand stuff they are not programmed to understand?



>

> If you were doing procurement, some application/procurement media type would

do. There can be <offer>,<order>,<invoice>, <creditNote>,... in that media type

without any need for further hints than Content-Type: application/procurement.

>

> Exactly the problem ... the client *still* needs to understand what <offer>,

<order>, <invoice>, and <creditNote> *mean*.  Why is it so cool to bury this

fact in two layers of negotiation (say "text/xhtml" plus a particular

microformat) than one?



It is not cool. It is wrong. The media type is the one layer that carries the

necessary information. (And sometimes we find link relations that make sense to

define in an orthogonal way (IANA link rels) to media types in order to

facilitate re-use).



Jan



>

> Jan

>

> Craig

>

> > If you were doing procurement, some application/procurement media type

> > would do. There can be <offer>,<order>,<invoice>, <creditNote>,... in that

> > media type without any need for further hints than Content-Type:

> > application/procurement.

> >

> > Exactly the problem ... the client *still* needs to understand what

> <offer>, <order>, <invoice>, and <creditNote> *mean*.



> Why is it so cool to

> bury this fact in two layers of negotiation (say "text/xhtml" plus a

> particular microformat) than one?



Because (quoting

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven) "REST is

software design on the scale of decades" and:



"What REST does is concentrate that need for prior knowledge into readily

standardizable forms [...]



It has value because it is far easier to standardize representation and relation

types than it is to standardize objects and object-specific interfaces. In other

words, there are fewer things to learn and they can be recombined in

unanticipated ways while remaining understandable to the client."



I am quite sure that the description of offers, quotes and so on varies with the

market/geographical-region/politics/time and other factors, whereas XML and JSON

won't. So XML/JSON are good candidates for media types whereas

offers/quotes/orders are not. Unfortunately JSON/XML carry no hypermedia

semantics so XHTML and RDF[a] are probably better examples.



But having only these "stupid", non-specific, formats leaves us with a need for

specifying how to interpret them in a domain specific manner - what they *mean*.

This is something that must be added on top of REST.



Thus we get "two layers of negotiation": one at the level of REST (the format of

the data - XML/JSON/RDF/XHTML/CSV/etc.) and one at a level higher up (the

meaning of the data - the ontology, or semantical interpretation of the data).



At the lower REST level it becomes a long lived application where we can expect

the formats to be readable over the decades. At the upper level we need to

upgrade our agents over time as the problem domain evolves.



(If you haven't noticed it then I am moving in the direction of the

do-not-mint-new-media-types camp).



/Jørn



--- In rest-discuss@yahoogroups.com, Craig McClanahan <craigmcc@...> wrote:

>

> On Thu, Dec 29, 2011 at 12:11 AM, Jan Algermissen <

> jan.algermissen@...> wrote:

>

> >

> > On Dec 29, 2011, at 8:19 AM, Jan Algermissen wrote:

> >

> > >

> > > On Dec 29, 2011, at 1:21 AM, Paul Cohen wrote:

> > >

> > > > or else a new HTTP header

> > > > "Concept-Type" could be introduced that indicates the

> > > > conceptual/business data type of the entity body, eg "Concept-Type:

> > > > purchase-order". This would at least give HTTP clients a *hint* of how

> > > > to interpret the entity body

> > >

> > > That 'hint' already exists and is called "Content-Type".

> >

> >

> > Consider, for example, application/atom+xml. This media type has two root

> > level document types, feeds and entries. There is no need to distinguish

> > between the two at the Content-Type header level because the user agent

> > simply reacts on what it receives.

> >

> > So, please explain for me again why application/atom+xml is better than

> application/procurement for this?

>

> Yes, I can understand (at a syntactic level) that I might receive a "link"

> element with a "rel" value of "checkout" and a corresponding URL.  But what

> the heck does a "rel" value of "checkout" *mean* in terms of what the

> client app should do next?

>

> Not negotiating content types at the HTTP media type level means I just

> have to negotiate them at some lower level (after I understand the syntax).

> That's not an improvement in interop ... that's just sweeping an

> inconvenient problem under the carpet.

>

>

> > If you were doing procurement, some application/procurement media type

> > would do. There can be <offer>,<order>,<invoice>, <creditNote>,... in that

> > media type without any need for further hints than Content-Type:

> > application/procurement.

> >

> > Exactly the problem ... the client *still* needs to understand what

> <offer>, <order>, <invoice>, and <creditNote> *mean*.  Why is it so cool to

> bury this fact in two layers of negotiation (say "text/xhtml" plus a

> particular microformat) than one?

>

>

> > Jan

> >

>

> Craig

>

> Thus we get "two layers of negotiation": one at the level of REST (the format

of the data - XML/JSON/RDF/XHTML/CSV/etc.) and one at a level higher up (the

meaning of the data - the ontology, or semantical interpretation of the data).



Actually, we might even get three layers in some cases:



1: choice of format (XML/JSON/XHTML/etc)



2: choice of encoding for some formats (XHTML + RDFa or HTML + microformat)



3: choice of semantics (XHTML + RDFa + Ontology)



/Jørn

On Thu, Dec 29, 2011 at 8:19 AM, Jan Algermissen

<jan.algermissen@...> wrote:

>

> On Dec 29, 2011, at 1:21 AM, Paul Cohen wrote:

>

>>  or else a new HTTP header

>> "Concept-Type" could be introduced that indicates the

>> conceptual/business data type of the entity body, eg "Concept-Type:

>> purchase-order". This would at least give HTTP clients a *hint* of how

>> to interpret the entity body

>

> That 'hint' already exists and is called "Content-Type".



Yes. I agree that the Content-Type header *is* used for the mixed

purpose of declaring both format types and conceptual types.



However my understanding of Media Type as defined in RFC 2046

(http://tools.ietf.org/html/rfc2046) is that it is to be used to

identify media format types or representation format types, and not

conceptual types. The Media Type spec defines the use of a two level

categorization hierarchy; "top level type" and "subtype". Both of

these category levels are to be used for naming media format types.



The fact that a) the media type spec does not specify how conceptual

types are to be identified and the fact that b) people have the need

to communicate information on conceptual types led to the convention

of defining media types with names like "application/*+xml", where *

is replaced with the name of some conceptual type.



The rationale for the "+xml" media type naming convention is found as

an appendix to the XML Media Types Spec RFC 3023

(http://www.ietf.org/rfc/rfc3023.txt); "Appendix A. Why Use the '+xml'

Suffix for XML-Based MIME Types?". To me it is a hack (as was also

noted by Erik Wilde earlier in this thread). I can appreciate the

rationale for interoperability and backwards compatibility that lead

to the "+xml" convention and I'm not categorically against the

convention of using the Content-Type header to specify both format

*and* conceptual type information. But I think this convention it is

one reason for why people are uncertain on how and where to handle

format and conceptual type information.



For example there exists a media type "application/calendar+xml" that

has an associated RFC specification 6321

(http://www.rfc-editor.org/rfc/rfc6321.txt). To me that is mixing the

format type (xml) with the conceptual type (calender; or actually an

iCalendar). Basically it is like saying "here is a resource

representing a calendar in the representation format of xml". What are

they to do when the need for a different representation format of a

calendar arises? Say for example JSON or PDF? Introduce new media

types "application/calendar+json" and "application/calendar+pdf"? Or

application/calendar+asn.1.BER? What if the need for an image-based or

audio-based representation of the calendar arises?



An obvious risk with the convention is that it will lead to a

over-proliferation of media types, since a new media type is needed

for each combination of format type and conceptual type. There are

already nearly 300 IANA registered mediatypes with "+xml" names. And

we are only starting to work on more complex "business" or

"conceptual" media types!



I think the web would be better served by support for a clear

distinction between format types and conceptual types. I think it also

would help people designing HTTP-based REST API:s. The concept that a

resource represents and the actual representation formats that are

available for that resource are two different things.



/Paul



--

Paul Cohen

www.seibostudios.se

mobile: +46 730 787 035

e-mail: paul.cohen@...

On Dec 29, 2011, at 3:43 PM, Paul Cohen wrote:



>

> However my understanding of Media Type as defined in RFC 2046

> (http://tools.ietf.org/html/rfc2046) is that it is to be used to

> identify media format types or representation format types, and not

> conceptual types.



There simply is no notion of 'conceptual type' in REST. All this does is

confusing the matter.



Servers can pick the representation (which media type to use and how to maybe

adjust the entity[1]) based on various request headers. If the existing request

headers (Accept-*) are not sufficient then define a sufficient media type.



Let me say it again: the problem that is being tried to solve does not exist.



Jan



[1] E.g. send this HTML to Firefox and that HTML to IE

On Thu, Dec 29, 2011 at 4:15 PM, Jan Algermissen

<jan.algermissen@...> wrote:

> On Dec 29, 2011, at 3:43 PM, Paul Cohen wrote:

> > However my understanding of Media Type as defined in RFC 2046

> > (http://tools.ietf.org/html/rfc2046) is that it is to be used to

> > identify media format types or representation format types, and not

> > conceptual types.

>

> There simply is no notion of 'conceptual type' in REST.



Errmh, no. I didn't say that either. I'm saying there are design and

implementation aspects of system interfaces that are not covered by

HTTP. At some level developers (human beings) need to communicate and

reason about the software they write. Every web service provides

information about something. Apart from the practical integration of a

client with a server we need to be able to discuss the "something"

rationale behind a given service. Otherwise I as a developer won't

know if the information of a given service is of interest to me. This

reasoning between developers (human beings) is at a conceptual level.

Furthermore software is not only meant for cumputers, it's also meant

for humans to read and understand and reason about.



Maybe the term "conceptual type" was unfortunate. My point in the

discussion was that it may be of interest to talk about the concepts

and information a service is meant to provide in order to then be able

to reason about what media types to use or invent for a given service.



> Let me say it again: the problem that is being tried to solve does not exist.



Is this your way of saying there is nothing to discuss? Or are you

saying there is no problem in deciding whether to define new media

types or not? My understanding of the discussion was that we were

discussing heuristics for inventing (or not inventing) new media

types.



/Paul



--

Paul Cohen

www.seibostudios.se

mobile: +46 730 787 035

e-mail: paul.cohen@...

On Dec 30, 2011, at 10:46 AM, Paul Cohen wrote:



> On Thu, Dec 29, 2011 at 4:15 PM, Jan Algermissen

> <jan.algermissen@...> wrote:

> > On Dec 29, 2011, at 3:43 PM, Paul Cohen wrote:

> > > However my understanding of Media Type as defined in RFC 2046

> > > (http://tools.ietf.org/html/rfc2046) is that it is to be used to

> > > identify media format types or representation format types, and not

> > > conceptual types.

> >

> > There simply is no notion of 'conceptual type' in REST.

>

> Errmh, no. I didn't say that either. I'm saying there are design and

> implementation aspects of system interfaces that are not covered by

> HTTP. At some level developers (human beings) need to communicate and

> reason about the software they write. Every web service provides

> information about something. Apart from the practical integration of a

> client with a server we need to be able to discuss the "something"

> rationale behind a given service.



No. You discuss the rationale behind service 'kinds' and that is part of setting

up the media type. The kind 'feed server' is (implicitly I guess) defined in the

media type spec. You do not talk about the AtomPub service X of organization Y.

All you need to know is that it is 'a feed server' and then you say Accept:

application/atom+xml, application/rss+xml and off you go. There is no need to

talk about *that* service any further. The description of the service *is* in

the media type. There are *no* (thatis: none whatsoever) service specific

descriptions in RESTful systems.





> Otherwise I as a developer won't

> know if the information of a given service is of interest to me. This

> reasoning between developers (human beings) is at a conceptual level.

> Furthermore software is not only meant for cumputers, it's also meant

> for humans to read and understand and reason about.



Right - but this is intent ("I want to buy a book, therefore I direct my browser

to http://amazon.de and not http://weather.info). No architectural style will

help to ensure the Amazon is still selling books tomorrow.



>

> Maybe the term "conceptual type" was unfortunate. My point in the

> discussion was that it may be of interest to talk about the concepts

> and information a service is meant to provide in order to then be able

> to reason about what media types to use or invent for a given service.



Well, 'entities' such as feeds, feed-entries, images, products, orders,

contact-info (vcard), events (icalendar) etc. surely are part of designing media

types.



>

> > Let me say it again: the problem that is being tried to solve does not

exist.

>

> Is this your way of saying there is nothing to discuss?



Yes :-) The whole strict point of 'specific media types are a bad idea' is

simply confusing people trying to understand REST. Maybe the discussion is

useful after all, though.



> Or are you

> saying there is no problem in deciding whether to define new media

> types or not? My understanding of the discussion was that we were

> discussing heuristics for inventing (or not inventing) new media

> types.



The thing is, that it is actually pretty clear that generic media types +

embedded specific stuff + a new means for negotiating that stuff is silly

because the mechanism for negotiation such stuff is the media type identifier in

the first place. It is the mechanism built into HTTP for that purpose.

(Not to question the usefulness of standard general link relations orthogonal to

media types, of course)



Specific media types is what one should do and there is no problem with them.

Yet, some people make it sound as if there is a problem - and this I find is

adding confusion for others that try to learn REST.



Jan



>

> /Paul

>

> --

> Paul Cohen

> www.seibostudios.se

> mobile: +46 730 787 035

> e-mail: paul.cohen@...

>