AW: 'expects' return value per status code?

@Markus: Indeed, I meant hydra:returns. Sorry for the confusion.



@Dietrich: Well, actually, I don’t “need” more than one hydra:returns in my use case. I just wanted to specify, in case of a 2.01 response to a POST request, the type of the created resource. I am not sure it is worth semantically describing the error types.



@Thomas: Indeed, perhaps I over-estimated the role of hydra:returns and hydra:expects.  I intended to use them for autonomous agents exploring the APIs. More precisely, I wanted to define a sub-class of hydra:Collection that contains only instances of a certain hydra:Class, and I was looking for a way to tell an agent that a POST request on the hydra:Collection creates a new instance of this hydra:Class (as it is often the case in a REST API). But I guess, this should be prior knowledge held by the agent.



@all: Thanks for the discussion. I now think it makes little sense to use explicitly a return value. However, the media type issue is relevant. I would rather have the same opinion as Ryan towards this; it might be relevant for input data.



Regards,

Victor Charpenay





Von: asbjornu@gmail.com [mailto:asbjornu@gmail.com] Im Auftrag von Asbjørn Ulsberg
Gesendet: Montag, 21. September 2015 15:43
An: Ryan McDonough
Cc: Karol Szczepański; Dietrich Schulten; Charpenay, Victor (ext); Hydra
Betreff: 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<mailto: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<mailto: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<mailto: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<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



      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