Re: ISSUE-31: Are Operations violating REST's uniform interface constraint? (was: More Thoughts on Links and Operation Subclasses)

On Feb 6, 2014, at 12:29 PM, Markus Lanthaler <markus.lanthaler@gmx.net> wrote:

>> On Wed, Feb 5, 2014 at 2:06 PM, Markus Lanthaler wrote:
>>> Great. So, before I close this issue I would like to get Mark's
>>> opinion (that's why I CCed you). Mark, do you agree with Ryan on
>>> this or do you think Operations do violate REST's uniform
>>> interface constraint?
>> 
>> I believe they violate the constraint, yes.
> 
> Let me ask a provocative question: Why do you think Operations violate the
> constraint whereas link relations, which further describe a potential GET
> request, don’t?


I’m very interested in this as well. But I think the GET request may be too trivial. Give the following Link header:

Link: <http://example.com/search>; rel="search"; title="Simple Search”

We could express this in Hyrda with something like:

“@id” : "http://example.com/search”,
“@type” : “search”

I don’t think that’s where Mark is concerned. Please correct me if I am mistaken Mark) 

I believe the area of concern  arises in the more detailed operations that send message. But since I’m missing it too, I thought I’d take a moment and create a search use case and express it in HTML, Open Search, and Hyrda.

In HTML we have:

<form id="search" action="http://example.com/search" method="POST">
	<input type="text" id="q"/>
	<input type="text" id="count"/>
	<input type="text" id="start"/>
</form>

Now I’m assuming here that HTML Forms do not violate the constraints as well. But HTML Forms seem to be okay [1].

And in OpenSearch with the Parameter Extension[2]:

<Url xmlns:parameters="http://a9.com/-/spec/opensearch/extensions/parameters/1.0/"
      template="http://example.com/search"
      parameters:method="POST"
      parameters:enctype="application/x-www-form-urlencoded">
   <parameters:Parameter name="q"/>
   <parameters:Parameter name="count"/>
   <parameters:Parameter name="start"/>
</Url>

And finally in Hydra:

{
   "@context": "http://www.w3.org/ns/hydra/context.jsonld",
   "@id": "http://example.com/search",
   "operations": [
     {
       "@type": "Search",
       "method": "POST"
       "expects" : {
       	    "@type": "hydra:Class",
       	    "supportedProperty": [
                {
                    "property": {
                        "@id": "q",
                        "@type": "rdf:Property",
                        "range": "http://www.w3.org/2001/XMLSchema#string"
                    },
                    "required": true,
                    "readonly": false,
                    "writeonly": false
                },
                {
                    "property": {
                        "@id": "count",
                        "@type": "rdf:Property",
                        "range": "http://www.w3.org/2001/XMLSchema#integer"
                    },
                    "required": false,
                    "readonly": false,
                    "writeonly": false
                },
                {
                    "property": {
                        "@id": "start",
                        "@type": "rdf:Property",
                        "range": "http://www.w3.org/2001/XMLSchema#integer"
                    },
                    "required": false,
                    "readonly": false,
                    "writeonly": false
                }
            ]
       }
     }
   ]
 }

When I look at all 3, I see a very generic HTTP POST request. Without a doubt, the Hydra version is more expressive we assume that the client will generate JSON-LD request that could also work equally well if it were sent as application/x-www-form-urlencoded. To my tiny monkey brain, these all feel like the same thing and I’m struggling to see how they are different? I am assuming of course that HTML forms DO NOT violate the uniform interface constraint.

Ryan-

[1] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
[2] http://www.opensearch.org/Specifications/OpenSearch/Extensions/Parameter


+-----------------------------------------------+
    Ryan J. McDonough (a.k.a John Yaya)
    http://damnhandy.com
    http://twitter.com/damnhandy