Subject: [core] #264: Content-Format of error responses

From: "Dijk, Esko" <[email-masked]>
Date: Thu, 6 Dec 2012 09:12:30 +0000

Hi Carsten,

> #264: How about defining a "diagnostic payload" as that in an error message that has payload but no Content-Format?

> So if a server does want to provide some HATEOAS payload for an error response, it will need to put in a Content-Format.

> Content-Format would remain optional for 2.xx responses.

Agree with a "diagnostic payload" to replace "diagnostic message" (sec 5.5.2). I assume any 2.xx, 4.xx or 5.xx response could use such a diagnostic payload then? (With exception of 2.05 - and maybe some others too?)

I also assume that we should state then that an implementation SHOULD NOT return a payload with Content-Format option value 0, if it actually intends this as diagnostic payload. (Rather than as an 'HATEOAS related response payload')

regards
Esko

________________________________
The information contained in this message may be confidential and legally protected under applicable law. The message is intended solely for the addressee(s). If you are not the intended recipient, you are hereby notified that any use, forwarding, dissemination, or reproduction of this message is strictly prohibited and may be unlawful. If you are not the intended recipient, please contact the sender by return e-mail and destroy all copies of the original message.

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 6 Dec 2012 10:25:07 +0100

On Dec 6, 2012, at 10:12, "Dijk, Esko" <[email-masked]> wrote:

> Agree with a “diagnostic payload” to replace “diagnostic message” (sec 5.5.2). I assume any 2.xx, 4.xx or 5.xx response could use such a diagnostic payload then? (With exception of 2.05 – and maybe some others too?)

In coap-12, diagnostic payloads are only available for error responses (4.xx, 5.xx).  Do we want to change that?

People seem to like being able to serve 2.05 with indeterminate Content-Format.  Reinterpreting success response payloads as diagnostic in the absence of Content-Format might be more consistent, but might also be surprising.

So what I was proposing was strictly for error responses.

> I also assume that we should state then that an implementation SHOULD NOT return a payload with Content-Format option value 0, if it actually intends this as diagnostic payload. (Rather than as an 'HATEOAS related response payload’)

Exactly.

Grüße, Carsten

---

From: "Dijk, Esko" <[email-masked]>
Date: Thu, 6 Dec 2012 09:30:20 +0000

> In coap-12, diagnostic payloads are only available for error responses (4.xx, 5.xx).  Do we want to change that?
Not a strong opinion on that.

For 2.xx responses it seems a server can still return a text string with a message and add Content-Format 0, as a "representation of the action result". So this would be a kind of diagnostic message in  disguise.

Esko

-----Original Message-----
From: Carsten Bormann [mailto:[email-masked]]
Sent: Thursday 6 December 2012 10:25
To: Dijk, Esko
Cc: [email-masked] WG
Subject: Re: #264: Content-Format of error responses

Exactly.

Grüße, Carsten

---

From: Klaus Hartke <[email-masked]>
Date: Thu, 6 Dec 2012 16:28:29 +0200

Carsten Bormann wrote:
> #264: How about defining a "diagnostic payload" as that in an error
> message that has payload but no Content-Format?

There are three types of representations that a response can transport:

* the representation of a resource state,
* the representation of the successful outcome of an action, and
* the representation of an error.

So "diagnostic payload" is the wrong term here.

coap-12 makes a special case for error responses in that these
actually do not transport a representation like any other response
type does, but a special "diagnostic message" with no option for other
formats. The ticket is simply about removing that special case and
transport a representation like all other responses.

The question is how to specify the content format of that
representation. For other representations types, this is done by using
the Content-Format Option, where an absent option means that the
implementation needs out-of-band information to correctly interpret
the data. The format of representations of errors should do the same,
although I guess it would be acceptable here to default an absent
Content-Format Option to "text/coap-diagnostic-message" or something
like that.

Klaus

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 6 Dec 2012 15:46:50 +0100

> * the representation of an error.

HTTP also has the status line.  We are trying to mirror that one here.
This is not a representation.  It does not have a media-type.

> transport a representation like all other responses.

Yes, I think we just discussed that, and came up with the solution in the SVN now.

> Content-Format Option to "text/coap-diagnostic-message" or something

That would be doing exactly the same thing, except that it would treat the status line information as a representation.
Whether that is a good thing or not has been the bike-shedding behind this ticket.
I personally believe that it is a good thing to keep status-line type information in the bowels of an implementation and not hand it up as a representation.  There won't be any HATEOAS links in a status-line.

Grüße, Carsten

---

From: Klaus Hartke <[email-masked]>
Date: Thu, 6 Dec 2012 16:51:10 +0200

> I personally believe that it is a good thing to keep status-line type information in the bowels of an implementation and not hand it up as a representation.  There won't be any HATEOAS links in a s…

Decide, then, if you want a status line or an error representation. If
status line, that's the diagnostic message we have right now in
coap-12. If error representation, call it error representation and
specify its media type.

Klaus

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 6 Dec 2012 15:59:50 +0100

> coap-12. If error representation, call it error representation and

The current text in the SVN contains one outcome of that decision.
It solves #264 (enabling HATEOAS for errors), but keeps the "status-line" type information for errors free of media-types.
Actually, the server implementer can decide whether it wants to provide a status-line type indication (most useful for 4.02 and friends) or a real error representation (most useful for, say, 4.01, 4.03, ...), simply by not including a Content-Format in the first case and including a Content-Format option in the second case.
It can't do both, but that will be rarely needed.  
It also can't send an indeterminate Content-Format for an error representation.
Both limitations seem OK to me.
The conceptual purity index is below 1.0, though, I admit.

Grüße, Carsten

---

From: Klaus Hartke <[email-masked]>
Date: Thu, 6 Dec 2012 17:09:25 +0200

Carsten Bormann wrote:
> Klaus Hartke wrote:
> Actually, the server implementer can decide

So, basically, you couldn't decide and now there are both options in
the draft, conflated into a "diagnostic payload" that is sometimes a
status line and sometimes an error representation with a media type...
I'm not sure if this is an improvement over coap-12.

Klaus

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 6 Dec 2012 16:18:43 +0100

> status line and sometimes an error representation with a media type...

Well, that's not what the text in the SVN says.  Please read it.
If there is a need for editorial improvements, let's take that offline.

Grüße, Carsten