Subject: [apps-discuss] Fwd: New Version Notification for draft-nottingham-json-home-01.txt

From: Mark Nottingham <[email-masked]>
Date: Thu, 5 Jul 2012 12:28:34 +1000

Begin forwarded message:

> From: [email-masked]
> Subject: New Version Notification for draft-nottingham-json-home-01.txt
> Date: 5 July 2012 12:22:04 PM AEST
> To: [email-masked]
> 
> 
> A new version of I-D, draft-nottingham-json-home-01.txt
> has been successfully submitted by Mark Nottingham and posted to the
> IETF repository.
> 
> Filename:	 draft-nottingham-json-home
> Revision:	 01
> Title:		 Home Documents for HTTP APIs
> Creation date:	 2012-07-05
> WG ID:		 Individual Submission
> Number of pages: 13
> URL:             http://www.ietf.org/internet-drafts/draft-nottingham-json-home-01.txt
> Status:          http://datatracker.ietf.org/doc/draft-nottingham-json-home
> Htmlized:        http://tools.ietf.org/html/draft-nottingham-json-home-01
> Diff:            http://tools.ietf.org/rfcdiff?url2=draft-nottingham-json-home-01
> 
> Abstract:
>   This document proposes a "home document" format for non-browser HTTP
>   clients.
> 
> 
> 
> 
> The IETF Secretariat

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

---

From: Peter Saint-Andre <[email-masked]>
Date: Mon, 16 Jul 2012 09:05:23 -0600

>>   This document proposes a "home document" format for non-browser HTTP

Hi Mark, this approach seems eminently sensible. I was expecting you to
also define a well-known URI at which to find home documents, but it's
not in the spec and I'm wondering why. :)

Peter

-- 
Peter Saint-Andre
https://stpeter.im/

---

From: Mark Nottingham <[email-masked]>
Date: Tue, 17 Jul 2012 09:42:25 +1000

> not in the spec and I'm wondering why. :)

I go back and forth on it. 

A few people have been encouraging me to do so, but I tend to think it sends the wrong message; that a hostname should always have just one home document, when there might be several views co-located on the same server (segregated by usage profile, user groups, "alternate views", etc.).

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 home documents are per-URI, this is easy; it just means pointing people to <http://api.example.com/new> or </v2> or whatever, whereas using a .well-known means that they HAVE to use a new hostname.

OTOH it's really powerful to "mix and match" a lot of different APIs into one home document, presenting a unified view, and that's one of the big use cases for the spec. A well-known would help with this.

In short, I'm still thinking about it, and what kinds of language I'd put around it; that's why it didn't make it into the recent rev.

Any input on either side would be most welcome.

Cheers,

---

From: Michiel de Jong <[email-masked]>
Date: Tue, 17 Jul 2012 10:23:24 +0200

hi!

i'm following this work with much interest. imho a well-known URI is
not immediately useful for the use case i'm imagining, which is client
developers using a generic code library for handling the interaction
with the API. We already see this now with OAuth, there are OAuth
client libraries in all popular languages that a programmer can use to
easily build a client for something. These libraries take
configuration files that are not human-memorable. An example i found
for one such library:

OAuthClientRequest request = OAuthClientRequest
            .authorizationLocation("https://graph.facebook.com/oauth/authorize")
            .setClientId("your-facebook-application-client-id")
            .setRedirectURI("http://www.example.com/redirect")
            .buildQueryMessage();

These libraries are already useful, even though their config is not
human-memorable. You have to spend some time installing such a library
into your project anyway, and learning how to work with it, so whether
you then paste a json-home URL or only a domain name into the code
that you build around such a library, is then a triviality.

imho, a well-known URI would be useful where the service provider is
chosen at run-time.

Two small comments that came to my mind when reading the doc:
1) i would love to have a way to make the relationship between the
/widgets/ and /widgets/{widget_id} URLs explicit. It would require
introducing the concept of items and collections, but I think many
APIs already use those concepts at quite a low level in their design.
Then, i could announce that a POST to a collection creates an item
(returning e.g. either the newly created object with its id inside it
in the body, or a Location: header to the newly created object).

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).

2) i think byte ranges are often supported for GET, even if they are
not supported for PUT. Should we interpret "accept-ranges": ["bytes"]
to apply to "maybe all, but at least one" of the methods?

My 2ct,
Michiel

On Tue, Jul 17, 2012 at 1:42 AM, Mark Nottingham <[email-masked]> wrote:
> _______________________________________________
> apps-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/apps-discuss

---

From: Mike Kelly <[email-masked]>
Date: Tue, 17 Jul 2012 09:49:18 +0100

If json-home is meant for representing entry points into an
application then it stands to reason that clients should already be
aware of its URI (the entry point of the API) and there should be no
requirement for reserving a well known address.

Maybe I'm missing something here?

Cheers,
M

-- 
Mike

http://twitter.com/mikekelly85
http://github.com/mikekelly
http://linkedin.com/in/mikekelly123

---

From: Mark Nottingham <[email-masked]>
Date: Wed, 18 Jul 2012 10:59:57 +1000

Hi Michiel,

> what a POST would do (because we can't talk of inserting without

Yep, I want to go there.

> to apply to "maybe all, but at least one" of the methods?

It's only for GET;
  https://svn.tools.ietf.org/svn/wg/httpbis/draft-ietf-httpbis/latest/p5-range.html#range.retrieval.requests

Cheers,