ODP: Re: 'expects' return value per status code?

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

<div>-------- Oryginalna wiadomość --------</div><div>Od: Ryan McDonough <ryan@damnhandy.com> </div><div>Data:20.09.2015  15:06  (GMT+01:00) </div><div>Do: Dietrich Schulten <ds@escalon.de> </div><div>DW: "Charpenay, Victor (ext)" <victor.charpenay@siemens.com>, Hydra <public-hydra@w3.org> </div><div>Temat: Re: 'expects' return value per status code? </div><div>
</div>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
 
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