Re: ISSUE-31: Are Operations violating REST's uniform interface constraint?

On Feb 16, 2014, at 11:27 AM, Thomas Hoppe <thomas.hoppe@n-fuse.de> wrote:

>> 
>> 
>> The @type of “Search” offers less value than the resource defined in the “expects” property. It’s here when’re it’s telling me how to format the message to the server. The operation subclass doesn’t do much in helping me achieve that. The majority of request formatting is expressed in #SearchRequest and not the #Search @type.
> 
> Hmm, for generic modelling of operations (or say forms because that would be the analogy in HTML)
> I think you are right -- in that case I don't care about the @type.
> But what If a client is specifically interested in a search operation of a Web resource.

I still believe that client doesn’t gain much with the @type of the operation. What the client must care about is how to prepare the request and deliver it over the correct HTTP method. The operation is being carried out by the information in the search request message, not the annotations around it. 

> In that case he might look for a well established operation like http://some.vocab.ns/Search
> and inspect how to format a request message in the second place.

Sure, but I can guarantee you that if this service is running over HTTP, there’d be only two operations to perform: GET or POST. I’m leaving out PUT, PATCH, and DELETE as they’re not applicable to a search use case. What the client needs to know now is:

* How do I send a “search” message to the service in order to get a response back?
* Do I need to send the message via GET or POST?

It’s not so much about describing the “operation” because we already know all of the HTTP operations that we can act on. At present, that’s about 5 in total (i’m excluding the WebDAV methods) that would be applicable to most applications. For me, it now boils down to formatting and transmission; how does the client prepare the message and what HTTP method do they send it with. I know I keep harping on HTML forms, XForms, and OpenSearch, but it’s because all of these formats operate on the same set of assumptions.

> Use-case: A generic client could use this information to present the user a search input when
> he browses a resource based on the existence of a search operation.

I still think this can be achieved. Checkout the JSONary project [1] and how they use JSON Hyper Schema [2] to dynamically generate HTML forms. If you take a gander at the Hyperschema docs, the link object for Hyperschema seems to follow the HTML approach and doesn’t give have any additional semantics around the Link and all of the descriptive effort is put into the “schema” property:

{
    "links": [
        {
            "rel": "search",
            "href": "/search”,
            “method” : “POST”,
            "schema": {
                "type": "object",
                "properties": {
                    "q": {
                        "type": "string"
                    },
                    "count": {
                        "type": "integer",
                        "minimum": 10,
                        "default": 20
                    },
                    "start": {
                        "type": "integer",
                        "default": 0
                    }
                },
                "required": [ "q" ]
            }
        }
    ]
}

Sure, it doesn’t look like much and JSON Schema itself still has a lot of holes. But it’s still plenty functional enough to build a generic client. It’s also simple and easy to work with and companies like Heroku [3] and GitHub are using this today. But if you squint a little, you can see that the "schema” is not very different than hydra:expects. Arguably, the link should probably be the value the “rel” property such that you’d have:

{
    "links": {
        "rel": {
            "href": "/search",
            "method": "POST",
            "schema": {
                "type": "object",
                "properties": {
                    "q": {
                        "type": "string"
                    },
                    "count": {
                        "type": "integer",
                        "minimum": 10,
                        "default": 20
                    },
                    "start": {
                        "type": "integer",
                        "default": 0
                    }
                },
                "required": [  "q"  ]
            }
        }
    }
}

But that’s likely for another forum.

Ryan-

[1] http://jsonary.com/
[2] http://json-schema.org/latest/json-schema-hypermedia.html
[3] https://blog.heroku.com/archives/2014/1/8/json_schema_for_heroku_platform_api

+-----------------------------------------------+
    Ryan J. McDonough
    http://damnhandy.com
    http://twitter.com/damnhandy