Subject: [ietf-types] Review of application/vnd.error+xml and application/vnd.error+json

From: Ben Longden <[email-masked]>
Date: Fri, 27 Apr 2012 16:32:45 +0100

Hi all,

I'm currently in the process of getting these two mime types registered - a blog post introducing the mime type is available at http://nocarrier.co.uk/2012/04/the-error-hypermedia-type/ and the standard itself is available at https://github.com/blongden/vnd.error

I'm looking for any feedback you may have to offer at this stage (changes, enhancements etc). The registration is as follows (I have only included the xml variant here - the json one has a sub mimetype name of vnd.error+json - otherwise the registration is identical).

Name : Ben Longden

Email : [email-masked]

MIME media type name : Application

MIME subtype name : Vendor Tree - vnd.error+xml

Required parameters : None

Optional parameters : None

Encoding considerations : binary

Security considerations : 
This media type provides a read only representation of an error state in an application. It does not contain any executable content. No privacy or integrity protection is provided; if either is needed they must be provided by some external service.

Interoperability considerations : None

Published specification :  https://github.com/blongden/vnd.error

Applications which use this media : None

Additional information :
1. Magic number(s) : N/A
2. File extension(s) : N/A
3. Macintosh file type code : N/A
4. Object Identifiers: N/A

Person to contact for further information :
1. Name : Ben Longden
2. Email : [email-masked]

Intended usage : Common
Author/Change controller : Ben Longden

--
Ben Longden
http://nocarrier.co.uk

---

From: Jan Algermissen <[email-masked]>
Date: Fri, 27 Apr 2012 19:08:52 +0200

Hi Ben,

> I'm currently in the process of getting these two mime types registered - a blog post introducing the mime type is available at http://nocarrier.co.uk/2012/04/the-error-hypermedia-type/ and the sta…

If I understand your intention correctly, these two media types are specifically designed to support the anti pattern of tunneling application specific semantics through HTTP.

The error communicated of an HTTP error response is specifically indicated by the HTTP status codes (4xx and 5xx). If you feel you need more specific error semantics, you are probably applying HTTP in the wrong way (as a transport to tunnel application semantics).

From the POV of playing nice with Web architecture I suggest you think about designing proper resource semantics instead.

Regarding the name vnd.error... I think this is an incorrect naming pattern in the vnd-tree, please check.

Having said that, I think you can achieve pretty much the same with a combination of Link-headers and text/html or text/plain and content negotiation to handle the i18n issue. What do you think?

Jan

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

---

From: Bjoern Hoehrmann <[email-masked]>
Date: Sat, 28 Apr 2012 01:24:51 +0200

>MIME subtype name : Vendor Tree - vnd.error+xml

This is using an outdated version of the template. The current one is in
RFC 4288, some field names are different and others are organized a bit
differently.

>Optional parameters : None

You should provide a rationale for using the "+xml" convention while
omitting the optional "charset" parameter of application/xml. The "+xml"
convention is meant to support "generic" processing, but if your type
does not have an optional 'charset' parameter, "generic" software would
not know how to process something like

  Content-Type: application/vnd.error+xml;charset=iso-8859-1

correctly, which I think is a problem.

>Applications which use this media : None

This is supposed to give people an idea whether this is a type that you
would use with word processing software, 3d rendering software, or some
such category of programs. It is not supposed to list individual pro-
ducts.
-- 
Björn Höhrmann · mailto:[email-masked] · http://bjoern.hoehrmann.de
Am Badedeich 7 · Telefon: +49(0)160/4415681 · http://www.bjoernsworld.de
25899 Dagebüll · PGP Pub. KeyID: 0xA4357E78 · http://www.websitedev.de/

---

From: Ben Longden <[email-masked]>
Date: Sat, 28 Apr 2012 22:09:45 +0100

Hi Jan,

Thanks for your comments.

> If I understand your intention correctly, these two media types are specifically designed to support the anti pattern of tunneling application specific semantics through HTTP.

I understand what you're saying... But I don't know how to respond to that. You could argue that point about any media type... How could you get application specific semantics from the server to the client without using HTTP? Even your example below is doing that. If you have a web api's then you *must* communicate using media types over HTTP. In the case of a web client, adopting this proposed standard means this is understood and disparate clients can understand the same message.

> The error communicated of an HTTP error response is specifically indicated by the HTTP status codes (4xx and 5xx). If you feel you need more specific error semantics, you are probably applying HTTP…

I am absolutely advocating the use of the HTTP status code - that's why I have excluded it from the proposed media type(s).

> Regarding the name vnd.error... I think this is an incorrect naming pattern in the vnd-tree, please check.

There are approved examples of excluding the vendor name from the vnd tree, (http://www.amundsen.com/media-types/collection/) being one. I shall check this out though.

> Having said that, I think you can achieve pretty much the same with a combination of Link-headers and text/html or text/plain and content negotiation to handle the i18n issue. What do you think?

I'd argue that a JSON representation with embedded links (_links in application/vnd.error+json) is a lot easier for javascript (one of the main consumers of this media type) to parse than link headers. Totally agree with con-neg to handle the i18n issue and have dropped the multi-lang stuff from the spec.

If I just use text/plain then I run into problems when I want to represent anything other than just the message (i.e, the id), and then have a requirement for a media type that can represent it.

BenLongden
http://nocarrier.co.uk

---

From: Ben Longden <[email-masked]>
Date: Sat, 28 Apr 2012 22:12:37 +0100

Hi Bjoern,

> RFC 4288, some field names are different and others are organized a bit

Thanks for that. I have incorporated your changes. Here is the updated document. Again - I wont repost the json equivalent as the differences should be fairly apparent!

   Type name: application

   Subtype name: vnd.error+xml

   Required parameters: none

   Optional parameters: charset (matching the specification for text/xml)

   Encoding considerations: binary

   Security considerations: This media type provides a read only representation of an error state in an application. It does not contain any executable content. No privacy or integrity protection is provided; if either is needed they must be provided by some external service.

   Interoperability considerations: none

   Published specification: https://github.com/blongden/vnd.error

   Applications that use this media type: Web applications

   Additional information:

     Magic number(s):
     File extension(s):
     Macintosh file type code(s):

   Person & email address to contact for further information: Ben Longden <[email-masked]>

   Intended usage: common

   Restrictions on usage: none

   Author: Ben Longden

   Change controller: Ben Longden

BenLongden
http://nocarrier.co.uk

---

From: Jan Algermissen <[email-masked]>
Date: Sun, 29 Apr 2012 02:29:27 +0200

Bi Ben,

On Apr 28, 2012, at 11:09 PM, Ben Longden wrote:

> I understand what you're saying... But I don't know how to respond to that. You could argue that point about any media type... How could you get application specific semantics from the server to the client without using HTTP?

The key here is that there is no application semantics *on top of HTTP* because HTTP already is a layer 7 protocol. The request and response entities are there to transfer data and controls (links, forms) but not additional (=beyond HTTP) methods or failure codes. If you do that, you have pure old RPC, not Web arch.

In stead of using such methods and codes, we need to design resource semantics in a way that the HTTP protocol is sufficient to realize the uses cases we want to build.

E.g. instead of having some "Order does not exist error" design an 'order' resource semantic and use 404. There is no error condition that you cannot express that way, in terms of the uniform interface that HTTP provides.

> Even your example below is doing that.

How so?

> If you have a web api's then you *must* communicate using media types over HTTP. In the case of a web client, adopting this proposed standard means this is understood and disparate clients can understand the same message.

The uniformity of HTTPs applies to the visibility components have in the *absence* of understanding the entity media types. A cache or monitoring intermediary can take action upon a 404, they cannot do that upon e.g. your proposed id="" attribute.

> I'd argue that a JSON representation with embedded links (_links in application/vnd.error+json) is a lot easier for javascript (one of the main consumers of this media type) to parse than link head…

Ok.

> If I just use text/plain then I run into problems when I want to represent anything other than just the message (i.e, the id), and then have a requirement for a media type that can represent it.

Hmm, but it is exactly the error-id that I am arguing against :-)

Jan

---

From: Bjoern Hoehrmann <[email-masked]>
Date: Sun, 29 Apr 2012 03:50:10 +0200

>   Optional parameters: charset (matching the specification for text/xml)

This should say `application/xml`.
-- 
Björn Höhrmann · mailto:[email-masked] · http://bjoern.hoehrmann.de
Am Badedeich 7 · Telefon: +49(0)160/4415681 · http://www.bjoernsworld.de
25899 Dagebüll · PGP Pub. KeyID: 0xA4357E78 · http://www.websitedev.de/

---

From: Ben Longden <[email-masked]>
Date: Sun, 29 Apr 2012 14:06:19 +0100

Hi Jan,

> E.g. instead of having some "Order does not exist error" design an 'order' resource semantic and use 404. There is no error condition that you cannot express that way, in terms of the uniform inter…

Yes and in that situation (Order does not exist), 404 would be the correct response. What if you POST an order for an item, however there is a validation error that prevents the request from being processed. I'd return a 422, perhaps with a text/plain response containing a simple error message. The problem is that without any extra semantics, I cannot for example link to a document that explains what the correct parameters are (accepted values etc), or identify which field contained the error message along side the human readable error.

> The uniformity of HTTPs applies to the visibility components have in the *absence* of understanding the entity media types. A cache or monitoring intermediary can take action upon a 404, they canno…

Agreed. I'm not advocating this as a replacement to the status code header. The id attribute is for carrying the specific reference to an error log entry on the server. This could be a URL (and perhaps should be a link with a defined rel in the spec, since out of bands information would be required to do anything with it!), but could be a database id with more specific information.

> Hmm, but it is exactly the error-id that I am arguing against :-)

Does that still hold true now that I have explained how I intended the id to be used? Perhaps changing this to a link with rel='service' (http://www.iana.org/assignments/link-relations/link-relations.xml) would make more sense.

Ben.

---

From: Ben Longden <[email-masked]>
Date: Sun, 29 Apr 2012 14:10:08 +0100

> This should say `application/xml`.

Yes it should. Amended. Thank you.

Ben

---

From: Jan Algermissen <[email-masked]>
Date: Sun, 29 Apr 2012 22:55:24 +0200

> Yes and in that situation (Order does not exist), 404 would be the correct response. What if you POST an order for an item, however there is a validation error that prevents the request from being…

Ah - I see. Thanks for clarifying. I really thought you meant to use id for the kind of error. Sorry for misunderstanding.

> Agreed. I'm not advocating this as a replacement to the status code header. The id attribute is for carrying the specific reference to an error log entry on the server. This could be a URL (and per…

URL sounds best. But I'll take a look at the issue from the 'new' angle. Might not be until Tuesday though.

Again, sorry for the confusion.

Jan