Re: 'expects' return value per status code?

Since 303 can’t prescribe an Accept header value it will fulfill, I don’t
think 303 solves any problems. As RFC 7231 states:

"If the header field is present in a request and none of the available
representations for the response have a media type that is listed as
acceptable, the origin server can either honor the header field by sending
a 406 (Not Acceptable) response or disregard the header field by treating
the response as if it is not subject to content negotiation.”

So the server can do whatever it pleases no matter what the client accepts.
It is therefore valuable information to provide the client with a hint of
what media type it will prefer to respond with. It should definitely be
stated that the media type is only a hint and that other media types can
(and probably will) be available, but the hint should be present
nonetheless, imho.

-- 
Asbjørn Ulsberg           -=|=-        asbjorn@ulsberg.no
«He's a loathsome offensive brute, yet I can't look away»

2015-09-21 12:54 GMT+02:00 Ryan McDonough <ryan@damnhandy.com>:

> In terms or response media types, I am not convinced that this is
> necessary. HTML has gotten by for years without the need to provide
> consumers hints as to what media type might be returned. If your client
> media type preferences don’t match what the server supports, the server
> should respond with a 303 providing you with a list of available media
> types for the resource. If you’re getting an error back from a proxy or
> gateway service, you may not be getting a media type that was listed in the
> Hydra document. If Hydra did have a media type option, clients would really
> have to use that as a hint or suggestion more than anything.
>
> I am also looking at this from the perspective of automated agents
> visiting various services without human intervention. In those cases, I
> don’t have the option of being able to code to to specific respond types.
> I’d send my agent out there with a set of media types it can handle and
> react to what the server gets back. Browsers work in a similar fashion. I
> only need to add plugins or helper apps after I received content I can’t
> handle. Having predefined media types works in more intimate environments
> like enterprises or services with more client knowledge.
>
> Input types is more interesting. My initial thought is that we’re assuming
> JSON-LD by default for all input types, but in the cases we are not, how do
> we indicate that the input type needs to be something other than JSON-LD.
> What are the valid media types this service takes for input? The classic
> file upload form in a good example. You can state that the form is being
> sent using multipart/form-data as opposed to
> application/www-form-urlencoded by specifying the enctype. HTML Forms is as
> close hydra:Operation in the wild that I can think of. I only bring it up
> it’s one of the few media types that actually execute on RESTful concepts.
> Having a means to define the encoding type for input operations is actually
> kind of important for use cases where one needs to send binary data with
> metadata.
>
> Ryan-
>
>
> On Sep 20, 2015, at 12:49 PM, Karol Szczepański <
> karol.szczepanski@gmail.com> wrote:
>
> Hi Ryan
>
> I'm having problem with not having anything related to media types. Indeed
> in case of as generic formats as XML, JSON or RDF we need some
> sophisticated mechanisms as Hydra itself to express what to expect inside
> such a payload, but media types are very ecpressive when it comes to other
> formats.
>
> Let's say you have an API that can provide a specified resource either in
> HTML or PDF formats. In both cases media types tells the client exactly of
> what to expect and how to process the payload, but in both cases it doesn't
> have anything to do witch clases or data structures in way Hydra
> understands them.
>
> Indeed HTTP provides a content negotitaition mechanism so client can try
> to obtain the resource in format understandable to it, but I'd really
> expect from the description vocabulary like Hydra to provide me some
> details in advance instead of relying on "on the fly" discovery of what's
> under the hood. As a use case I'd show show proper UI details of what can
> be done by a user before actually flooding server with unnecesery requests.
>
> Thats my opinion anyway
>
> Regards
>
> Karil Szczepański
>
>
> -------- Oryginalna wiadomość --------
> Od: Ryan McDonough
> Data:20.09.2015 15:06 (GMT+01:00)
> Do: Dietrich Schulten
> DW: "Charpenay, Victor (ext)" , Hydra
> Temat: Re: 'expects' return value per status code?
>
> I raised a similar issue about year ago in the discussion around Operation
> subclasses:
>
> https://lists.w3.org/Archives/Public/public-hydra/2014Jan/0058.html
>
> I still look at example 10 on the current published spec to mean that the
> expect and returns properties to assume that we’re still dealing with
> JSON-LD:
>
> {
>   "@context": "http://www.w3.org/ns/hydra/context.jsonld",
>   "@id": "http://api.example.com/doc/#comments",
>   "@type": "Link",
>   "title": "Comments",
>   "description": "A link to comments with an operation to create a new
> comment.",
>   "supportedOperation": [
>     {
>       "@type": "CreateResourceOperation",
>       "title": "Creates a new comment",
>       "method": "POST",
>       "expects": "http://api.example.com/doc/#Comment",
>       "returns": "http://api.example.com/doc/#Comment",
>       "possibleStatus": [
>         ... Statuses that should be expected and handled properly ...
>       ]
>     }
>   ]
> }
>
> But, I believe I am reading this slightly incorrectly. If what I am
> gathering from Ruben’s comments, the values from expects and returns are
> descriptions about what is being returned has nothing to do with the actual
> representation. I notice that the hydra:mediaType has been dropped, which
> is excellent! Comment for example, could be submitted using "application/x-www-form-urlencoded”and
> returned as text/csv? Therefore, you should be able to use HTTP content
> negotiation to express your media type preferences.
>
> If I’m groking everything correctly, then we’re using JSON-LD to express
> the information in the expected and returning resources and not suggest
> anything about the representation format. This fields would only provide
> hints as to what information is contained within the response, but not
> necessarily the media type used to represent it. Does that sound about
> right?
>
> Ryan-
>
>
>
> On Sep 20, 2015, at 8:17 AM, Dietrich Schulten <ds@escalon.de> wrote:
>
> Hi Victor,
>
> could you explain a bit more how status code and response body are related
> in your design, maybe give an example? Are we talking about error responses
> at all?
>
> Best regards,
> Dietrich
> Am 17.09.2015 15:36 schrieb "Charpenay, Victor (ext)" <
> victor.charpenay@siemens.com>:
>
> Hi everybody,
>
> as I was designing a Hydra spec, I stumbled upon this little issue: I have
> different expected return values, depending on the status code that is
> responded.
>
> Has anybody already raised this issue? Would it make sense to change the
> range of ‘hydra:expects’ so that it could include both a
> StatusCodeDescription and a hydra:Class?
>
> Sincerely,
> Victor Charpenay
>
> Siemens AG
> Corporate Technology
> Research and Technology Center
> CT RTC NEC ITH-DE
> Otto-Hahn-Ring 6
> 81739 München, Deutschland
> *mailto:victor.charpenay@siemens.com* <victor.charpenay@siemens.com>
>
> Siemens Aktiengesellschaft: Vorsitzender des Aufsichtsrats: Gerhard
> Cromme; Vorstand: Joe Kaeser, Vorsitzender; Roland Busch, Lisa Davis, Klaus
> Helmrich, Janina Kugel, Siegfried Russwurm, Ralf P. Thomas; Sitz der
> Gesellschaft: Berlin und München, Deutschland; Registergericht: Berlin
> Charlottenburg, HRB 12300, München, HRB 6684; WEEE-Reg.-Nr. DE 23691322
>
>
>
>