verbs and mappings

Poster Content
nk4um User
Posts: 112
June 26, 2012 18:37

Posted by Randy Kahle (View)

Do mean that you create URI schemes for domain concepts such as

customer:xxx

and make requests such as SOURCE and SINK to them?

If not, I'm curious for more details about your approach.

Thanks -- Randy

Yes, this is pretty much it. I'm most often able to do it when the resources are actual document-like things on other systems, for example we have an xml database, and we implemented a uri scheme to access the documents there as

xmldb:/document/path/whatever.xml

In some cases these are implemented simply as mappings to http requests with parameters (say, http://xml-database.example.com/get-file?path=/document/path/whatever.xml), but from the outside it's a simpler, more descriptive, and less noisy name for the resource.

For less document-y things like a customer record in a rdbms, the SOURCE implementation is fairly easy, but the SINK implementation has questions about how best to do it, for example, can you do a partial update if the logical record spans multiple tables, or should you always update everything. The latter is preferable from a REST point of view, but it aggravates the efficiency gland that most engineers have :)

Like · Post Reply
nk4um User
Posts: 13
June 22, 2012 22:54

Posted by jrogers (View)
...

In my own designs I try to follow good verbing principles. For things that are exchanges of resources, I implement a uri scheme to SOURCE or SINK to.

...

Do mean that you create URI schemes for domain concepts such as

customer:xxx

and make requests such as SOURCE and SINK to them?

If not, I'm curious for more details about your approach.

Thanks -- Randy

Like · Post Reply
nk4um User
Posts: 9
May 16, 2012 03:44

Hadn't seen that particular one, but this topic has been around for a while. See for example, http://www.1060.org/nk4um/topic/372/

He-he...I'm the 'hickst' in that discussion. Thanks, I'd forgotten about that one.

  cheers,
  -tom
Like · Post Reply
nk4um User
Posts: 112
May 16, 2012 01:29

OK, so if I understand you now, your new INVOKE verb means something like: "I'm going to activate the endpoint identified by this URI but I don't expect any content (resource representation) to be returned" (I might still expect an acknowledgement or status return code)?

Yes.

"I'd suggest a verb is just a flag to indicate a particular mode of state transition." and "I sense that a verb is actually an additional part to the identifier." I'm not sure I understand all the ramifications of this view but, if this is a better way to conceive of VERBs in the ROC paradigm, then I would expect the VERB to figure prominently in resource resolution (and I don't think it does now, does it?).

This is where I started from: verbs are just part of the request. (fun fact: many webservers don't care at all about the http method being one of the predefined ones, they just pass it along to the appropriate handler, which in some cases is closely tied to the request uri, and in some cases is tied to the method+request uri! And typically the request method is usually handled as just a string.)

However, if you look at the codebase, you see a different story. IRequest defines the 9 verbs I mentioned above. NKFEndpointImpl suggests that you implement onSource or onSink as appropriate. A developer could be forgiven for thinking that verbs are fundamental.

BTW, are you aware of this highly related, predecessor thread? http://www.netkernelroc.org/nk4um/topic/71/

Hadn't seen that particular one, but this topic has been around for a while. See for example, http://www.1060.org/nk4um/topic/372/

Like · Post Reply
nk4um User
Posts: 9
May 15, 2012 23:20

OK, so if I understand you now, your new INVOKE verb means something like: "I'm going to activate the endpoint identified by this URI but I don't expect any content (resource representation) to be returned" (I might still expect an acknowledgement or status return code)?

I think the INVOKE verb is a great thought experiment because it makes us think about just what the purpose of the VERBs is anyway. Because they are imperative, I think there is a tendancy to see them as commands to the endpoint (albeit limited and vague commands) instructing it how to behave. In the REST model, I think this is how VERBs are generally construed (although, alternatively, we might think of VERBs (HTTP methods) as just specifying the client's intention (an important distinction?)).

In the recent newsletter article that started all this (see: http://wiki.netkernel.org/wink/wiki/NetKernel/News/3/23/May_11th_2012#On_State_and_Reality), Peter provides some other perspective: "I'd suggest a verb is just a flag to indicate a particular mode of state transition." and "I sense that a verb is actually an additional part to the identifier." I'm not sure I understand all the ramifications of this view but, if this is a better way to conceive of VERBs in the ROC paradigm, then I would expect the VERB to figure prominently in resource resolution (and I don't think it does now, does it?).

BTW, are you aware of this highly related, predecessor thread? http://www.netkernelroc.org/nk4um/topic/71/

Like · Post Reply
nk4um User
Posts: 112
May 15, 2012 21:31

This has nothing to do with the endpoint, aside from the endpoint implementing the proper and expected semantics - exactly as it is now.

I'm not suggesting that the "active:" uri scheme is somehow magically tied to the "INVOKE" verb, but rather that there should be an INVOKE verb that an active: accessor like say "active:cronNew" supported, where the name of the verb suggests that it is doing something rather than requesting a resource be returned which is what SOURCE suggests.

In line with the earlier ones, my diagram for INVOKE would be

{} -> INVOKE -> {}

That is, it takes no input and gives no output.

Now of course the implementation of the "file:" scheme could implement INVOKE - maybe as an alternative to active:exec - but in general it wouldn't make sense so you shouldn't do it.

Like · Post Reply
nk4um User
Posts: 9
May 15, 2012 20:21

Posted by jrogers (View)
This seems to be a point about consistency of use. I'm all for consistency so it makes me wonder if there are explicit guidelines for programmers to use when choosing to implement ROC verbs?

This is really the core of the point I'm trying to make. From what I can tell, there aren't explicit guidelines.

I don't know that there aren't written guidelines: I haven't checked all the documentation, but I don't remember seeing them.

...it could also be CALL or REQUEST or something else. And that verb would generally apply to doing things - i.e., active: uris - and would not apply to uri schemes like file:. Of course it would be up to the user to make it do the right thing, but it would be a stronger suggestion about what the right thing is.

Ooh....sorry, but here I have to strongly disagree. I think this is exactly counter to a fundamental principle of ROC: the user of a URI does not/should not have to know *anything* about the endpoint which responds to the request (except what the arguments to the request are, of course). In fact, in NK the endpoint which responds to a given request can be dynamically created and/or "discovered" and your request can be dynamically "rerouted" depending on any number of other non-intrinsic factors (e.g. time of day, originating network, the frequency of your requests, and so on).

So I don't believe that the active: URI is about what type of endpoint one is "calling" but about how easy it is to provide complex arguments to the endpoint (as opposed to the "standard" URI).

Like · Post Reply
nk4um User
Posts: 112
May 15, 2012 19:57

This seems to be a point about consistency of use. I'm all for consistency so it makes me wonder if there are explicit guidelines for programmers to use when choosing to implement ROC verbs?

This is really the core of the point I'm trying to make. From what I can tell, there aren't explicit guidelines. And there should be. But SOURCE is instead a catch-all - it sources, it updates, it manages dependencies, it spawns subprocesses, it schedules jobs, etc.

To sharpen the point a bit, URI schemes are generally good. pds: or file: or httpRequest: and httpResponse - they support verbs in a sensible way. active: uris on the other hand, are a complete mismatch for the standard verbs. Often they do not represent any exchange of resource or state, but rather an action that takes place. The "active:" part suggests that, but the SOURCE verb then confuses things.

In my own designs I try to follow good verbing principles. For things that are exchanges of resources, I implement a uri scheme to SOURCE or SINK to. For things that are actions, I have a wrapper function "invoke()" - it SOURCEs the indicated resource and discards the result. Well, not exactly: it does return the result, but the typical use is to drop it, and the name tries to reflect that. There's another wrapper function "get()" that is intended for retrieving a resource.

It would be helpful to ROC if there was a different verb for these uses that did not suggest a particular flow of resources. I'd suggest "INVOKE", but it could also be CALL or REQUEST or something else. And that verb would generally apply to doing things - i.e., active: uris - and would not apply to uri schemes like file:. Of course it would be up to the user to make it do the right thing, but it would be a stronger suggestion about what the right thing is.

Like · Post Reply
nk4um User
Posts: 9
May 15, 2012 19:08

Some thoughts (in no particular order):

I think you answered your own (implied) question: ROC is NOT REST.

All transports convert the messages of the external paradigm into the messages of the ROC paradigm, including the verbs (e.g. JMS and SMTP). REST is a closer family member than these others, leading to the confusion. So, I agree that NK should do a better job of distinguishing itself from REST. But, how to do that except through education and documentation (and discussions like this)?

You can always define your own mapping of REST -> ROC. This used to be harder but appears to have been recently simplified with the verbTranslate (http://wiki.netkernel.org/wink/wiki/NetKernel/News/3/22/May_4th_2012).

Why isn't the accessor to convert JSON to XML called as TRANSREPT?

This seems to be a point about consistency of use. I'm all for consistency so it makes me wonder if there are explicit guidelines for programmers to use when choosing to implement ROC verbs?

Finally, I'm not sure what you mean by your last point: ROC *is* something, it's something with fewer hard constraints than REST.

   cheers,
   tom hicks
Like · Post Reply
nk4um User
Posts: 112
May 15, 2012 18:26verbs and mappings

(see: http://wiki.netkernel.org/wink/wiki/NetKernel/News/3/23/May_11th_2012#On_State_and_Reality)

You're going to find that many of the truths we cling to depend greatly on our own point of view. —Obi-Wan Kenobi

This question of verb mappings has come up many times before, and I suspect will continue to come up again in the future. "Why does no one understand?" Peter seems to be asking.

On the one hand is the claim that there's nothing special about verbs, that the "request" is the fundamental operation and verbs are merely another parameter to a request. (I'll horrify Peter and ignore "scope" ).

On the other hand is the system itself - verbs are explicitly defined. Methods for handling those verbs are explicitly defined.

So I think one place where confusion arises is that developers generally expect particular verbs to have particular semantics, but those particular semantics are only one realization of the infinite possibilities that they could be.

To be a little more concrete: REST defines 4 verbs, that correspond roughly to database CRUD operations. POST = create, GET = read, PUT = update, DELETE = delete. (more or less, depending on your particular preference - you might swap PUT and POST in that definition, but that's not important). Each request is a verb and an identifier, and depending on the verb may have a content body. They each have particular semantics, especially concerning idempotency.

ROC (i.e., netkernel) defines 9 verbs: DELETE, EXISTS, FRAGMENT, META, NEW, RESOLVE, SINK, SOURCE, and TRANSREPT. Every endpoint that implements these verbs may choose to implement different semantics. Not all have identifiers (that I can tell). Some support a "primary" argument, but that's just a fancy name for some specially named argument that the implementation can choose to handle specially, or not. Idempotency is at the discretion of the implementor.

So if you're a REST purist, then GET only retrieves representations and never changes anything. In ROC, SOURCE should be the same, right? Well, no - it's perfectly acceptable for SOURCE to cause an action to happen. In REST, you should be able to PUT to any address and have the resource updates. In ROC, SINK should do that, right? Well, not really ... only a handful of accessors implement SINK at all. On those it generally does what is expected - except that the identifier that SINK operates on is completely unrelated to what you would SOURCE (in terms of how the system views them).

I wouldn't be surprised if Peter has Feynman diagrams of various ROC requests, but the way I usually think of the common ones is:

{} -> SOURCE -> {thing}

{thing} -> SINK -> {}

{thing} -> TRANSREPT -> {thing'}

That is, a SOURCE takes no input and gives a result. SINK takes an input and gives no result. TRANSREPT takes an input and gives a different result.

This is mostly how things work, but there are enough places where it doesn't to make things confusing. For example, why do you SOURCE a sql update? Why isn't the accessor to convert JSON to XML called as TRANSREPT? How do you model POST, the catch-all of REST verbs?

Anyways, enough of my ramblings. The main point I wanted to make is that even though ROC is everything, it also needs to be *something*, and when that something isn't REST but developers think it is, confsuion results.

Like · Post Reply