Subject: [apps-discuss] Avoiding sending out 'problematic' signals with jason-home

From: Jan Algermissen <[email-masked]>
Date: Wed, 18 Jul 2012 16:55:11 +0200

Hi Mark,

[sorry, I had somehow unsubscribed from the list and hence cannot reply to the postings I mention below]

in [1] you responded:

"E.g., I believe that "versioning" an API should involve minting a new home document, and serving both side-by-side for a period."

If something like this would make it into the draft I think it would send out wrong impressions. FWIW, versioning happens at the media type / conneg level and URIs should remains stable. Granted there can be exceptions, but once you hand out 'versioning capabilities' to the world they'll all just jump on it like crazy because it satisfies SOAPy brains too easily.

You crafted the wording of the 'hints' section so carefully, but I am still sure, people will thankfully mistake it as a design-time WADL-like tool. Let's not add 'versioning' to that.

-----

In [2] you respond:

<snip>
> Right now i see how the client will have default expectations of what
> GET, PUT, DELETE and PATCH will do (namely, read, write, remove,
> modify), but i would not know how to define default expectations of
> what a POST would do (because we can't talk of inserting without
> talking of collections).

Yep, I want to go there.
</snip>

Umm, am I missing something?

The expectations a client can have regarding the POST are already sufficiently defined by the target resource semantics the client understands from understanding the link relation it follows.

The expectations regarding methods are not a 'default' that can be extended. HTTP already defines their meaning. Adding expectations on to means creating a new protocol.

I really do think that something as clean and simple as json-home moves us a great step forward in terms of handing wanna-be REST adopters the necessary tools!

But I also think it is a very slippery slope regarding the issue of helping adopters to actually go through a mind shift away from RPC towards a use of HTTP that actually brings them the benefits they expect from it. Any RPC-ish touch will make that shift harder, IMHO.

Jan

[1] http://www.ietf.org/mail-archive/web/apps-discuss/current/msg06700.html
[2] http://www.ietf.org/mail-archive/web/apps-discuss/current/msg06709.html

---

From: Mark Nottingham <[email-masked]>
Date: Thu, 19 Jul 2012 15:48:28 +1000

Hey Jan,

> You crafted the wording of the 'hints' section so carefully, but I am still sure, people will thankfully mistake it as a design-time WADL-like tool. Let's not add 'versioning' to that.

I probably think of "versioning" in a way that's different to most people, to the point where I probably shouldn't use that word, sorry.

I see a home document being a collection of resource objects that is added to over time; you can make backwards-compatible changes by adding new relations to it, or by some kinds of modifications to it.

At some point far in the future, that home document *might* get so bloated and crufty that you decide to mint a new one. At that point, you'd create a new home document and direct new users to it, encouraging old users to upgrade. That's what I mean by "versioning" the home document. 

Evolving (I'll avoid the "V" word) the individual formats and relation types used is indeed an entirely separable and separate thing.

Now, to the original discussion; could you do that new home document on a new hostname? Certainly (e.g., if you're on api.example.com, you could mint new-api.example.com). A few sites have already followed this pattern roughly, IIRC. I'm still not quite sure a .well-known is necessary, tho.

> The expectations regarding methods are not a 'default' that can be extended. HTTP already defines their meaning. Adding expectations on to means creating a new protocol.

I'm talking about a hint that lets clients know that they can create a resource with a given relation by POSTing to a particular resource; nothing more. It's a common enough pattern that it's useful to surface.

It's really just a shortcut; the link relation type + media type still define the semantics of POSTing to the resource, it's just surfacing this information in an easy-to-read way for a common case. Think of it as a mini-form.

Is that less concerning?

> But I also think it is a very slippery slope regarding the issue of helping adopters to actually go through a mind shift away from RPC towards a use of HTTP that actually brings them the benefits t…

Absolutely; that's exactly why I'm treading so gingerly.

Cheers,

--
Mark Nottingham   http://www.mnot.net/

---

From: Mike Kelly <[email-masked]>
Date: Thu, 19 Jul 2012 09:23:06 +0100

> It's really just a shortcut; the link relation type + media type still define the semantics of POSTing to the resource, it's just surfacing this information in an easy-to-read way for a common case…

So is it intended that automated clients would use this control when
making the request? Or is it just a bit of extra sugar to help a
humans when they're exploring the API?

I'm assuming the latter, as I can't see how the former would work in practice.

Cheers,
M

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 20 Jul 2012 11:02:27 +1000

> I'm assuming the latter, as I can't see how the former would work in practice.

For example, a client library could expose a call that lets a developer create a new resource of a given relation type.

Cheers,

---

From: Mike Kelly <[email-masked]>
Date: Fri, 20 Jul 2012 08:34:46 +0100

> For example, a client library could expose a call that lets a developer create a new resource of a given relation type.

Right, but how would the selection of method be made by the code? Would it be dynamic depending on what's in the allow hint? How would that logic deal with a change that removed PUT and replaced it with POST?

Cheers,
M

---

From: Jan Algermissen <[email-masked]>
Date: Sat, 21 Jul 2012 14:14:09 +0200

> At some point far in the future, that home document *might* get so bloated and crufty that you decide to mint a new one. At that point, you'd create a new home document and direct new users to it,…

Ok, understood. Thanks for clarifying.

> Now, to the original discussion; could you do that new home document on a new hostname? Certainly (e.g., if you're on api.example.com, you could mint new-api.example.com). A few sites have already…

Could a combination with OPTIONS, redirects and/or link headers work?

Maybe a slight modification (while you are still at it :-) of the OPTIONS definition would allow that?

However, I think that if you are in a scenario, where you discover services completely (e.g. by asking DNS for instances of a service type) the result will likely include a URI to turn to anyhow. And if you are in a situation where primary entry URIs of services are exchanged between parties up front those URIs can well be home document URIs. It is unlikely that it will ever only be the domain name alone, IMO.

I'd say well known locations are not necessary.

Jan