Re: 'expects' return value per status code?

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 <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 <http://www.w3.org/ns/hydra/context.jsonld>",
>   "@id": "http://api.example.com/doc/#comments <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 <http://api.example.com/doc/#Comment>",
>       "returns": "http://api.example.com/doc/#Comment <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 <mailto: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 <mailto: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 <mailto: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
>