Subject: [apps-discuss] FYI: "home" document format for APIs

From: Mark Nottingham <[email-masked]>
Date: Thu, 10 May 2012 14:28:02 +1000

Some people might be interested in a draft I've started work on:
  http://tools.ietf.org/html/draft-nottingham-json-home

Feedback / thoughts / pull requests welcome.

Cheers,

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

---

From: Mike Jones <[email-masked]>
Date: Thu, 10 May 2012 17:56:11 +0000

In your FAQ you covered a number of pieces of related work (which was great), but not the relationship of this work to WebFinger, Simple Web Discovery, LRDD, JRD, or host-meta.  Could you share your thoughts those as well?

				Thanks,
				-- Mike

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Mark Nottingham
Sent: Wednesday, May 09, 2012 9:28 PM
To: Apps Discuss
Subject: [apps-discuss] FYI: "home" document format for APIs

Cheers,

_______________________________________________
apps-discuss mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/apps-discuss

---

From: Martin Thomson <[email-masked]>
Date: Thu, 10 May 2012 11:40:40 -0700

>  http://tools.ietf.org/html/draft-nottingham-json-home

My first thought: thanks very much.

A question or two:

Section 4: Why always absolute URIs for href-vars?  For a private
relation type, small textual labels seem reasonable.  Or would you
simply advocate for omitting href-vars in favour of consistent labels
in those cases?

Versioning?  Some find it distasteful, but pragmatically it's very useful.

A nit:

Section 3: s/links two a resource/links to a resource/

--Martin

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 11 May 2012 06:34:28 +1000

I think they're orthogonal. My understanding of all of those mechanisms is that their goal is to take a non-URI identifier (e-mail address, domain name, whatever) and get data / metadata about it. 

This is just a document format, to be given a URL. Of course, you could point at it with a non-URL, but like I said, that's orthogonal.

Cheers,

---

From: Ben Niven-Jenkins <[email-masked]>
Date: Thu, 10 May 2012 22:56:08 +0100

Mark,

> Feedback / thoughts / pull requests welcome.

On a few occasions I've had the need for what is described in your draft and ended up designing something from scratch. Having a standardised document format to use/refer to would be better than everyone designing similar but different formats IMO.

Ben

---

From: Mike Jones <[email-masked]>
Date: Thu, 10 May 2012 22:27:15 +0000

JRD http://tools.ietf.org/html/rfc6415#appendix-A is a JSON document format used for discovering information about a host, service, or user.  I don't think that's orthogonal to your goals, unless I misunderstand them.  Could you take a crack at doing a comparison?

				Thanks,
				-- Mike

-----Original Message-----
From: Mark Nottingham [mailto:[email-masked]] 
Sent: Thursday, May 10, 2012 1:34 PM
To: Mike Jones
Cc: Apps Discuss
Subject: Re: [apps-discuss] FYI: "home" document format for APIs

Cheers,

---

From: James M Snell <[email-masked]>
Date: Thu, 10 May 2012 15:47:00 -0700

How does this compare to what Google has done with their "discovery
service" API .. The JSON-based format they use is described here [1]
and is generally much more expansive in detail but overlaps much of
the same functionality. (note, the relevant IP details for google's
format are described here [2])

[1] https://developers.google.com/discovery/v1/reference#resource_discovery
[2] https://developers.google.com/discovery/patent-license

- James

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 11 May 2012 12:33:04 +1000

Thanks for the feedback, Martin. Responses below.

> simply advocate for omitting href-vars in favour of consistent labels

It's necessary to have a global identifier for them; a local one doesn't do any good.

While we could us a prefixing / base url approach, I'm reluctant to add that level of complexity / processing to JSON. Thoughts?

> Versioning?  Some find it distasteful, but pragmatically it's very useful.

Can you be more specific? What needs to be versioned, in your view?

> Section 3: s/links two a resource/links to a resource/

ack.

Thanks again,

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 11 May 2012 13:12:56 +1000

I'd say there are *lots* of people doing this sort of thing now; the trick is to have a single, non-vendor-specific and non-application-specific way to do it, that's described in a standalone doc and stable.

The other trick is to avoid it becoming WSDL, WADL or another DL-ish thing.

Cheers,

---

From: Graham Klyne <[email-masked]>
Date: Fri, 11 May 2012 08:04:11 +0100

>    http://tools.ietf.org/html/draft-nottingham-json-home

Hi Mark,

I think this is interesting and timely.

I've been specifying something similar for two projects I'm working on (one a 
W3C work-in-progress), but I've tended to use RDF as that saves me having to 
describe a syntax as well as the required link relations.

While I don't think it would be helpful to describe the home document format 
*as* RDF, I think it would be good to have a clear mapping to an RDF model - the 
currently defined format is, I think, very close to an RDF-like structure: the 
language of "link relations" is, in any case, very much like RDF.  This might 
also help to address the open issue of minting new hints without requiring a 
registry.  I'd be happy to work with you on an appendix to describe such a 
mapping (which would explicitly *not* change the format as defined).

(Indeed, with just one Link: header, I think the home document could be 
interpreted as RDF per http://json-ld.org/spec/latest/json-ld-syntax/ as it 
stands.  This is a property I'd like to see preserved.)

A coupe of more specific comments:

Section 4.1:

I found the text in the last paragraph took 2-3 passes to grok.  I think it 
relates to an important (if not the key) feature of the home document, and maybe 
the idea needs to be explained more carefully.

General:

It's kind-of implicit in the section 7 "Consuming ..." description, but for 
extensibility it might be worth making an explicit statement about ignoring any 
link relations or object fields that are not understood.

Also, in addition to the defined fields (href, hints, etc), and within a hints 
object, allow any service to include additional fields keyed by URIs, so that 
private-use extensions can be introduced and trialed.

Appendix B: open issues:

    o  Refining and extending representation formats - "application/xml",
       for example, isn't enough.  While a media type for every
       representation is one answer, something like 'profile' might be
       good too.

Maybe one might draw upon the media features registry for keying additional 
information?  http://tools.ietf.org/html/rfc2506

    o  Object for contact details - do we need an object that describes
       who's running the API, etc?

Seems reasonable...

    o  Defining new hints - guidance is needed on minting new hints.
       Possibly a registry.
    o  Defining new top-level properties - how new ones are minted,
       registry, etc.
    o  Defining new Resource Object properties - how new ones are minted,
       registry, etc.

And/or URIs for private-use.  See above.

#g

---

From: James M Snell <[email-masked]>
Date: Fri, 11 May 2012 11:16:59 -0700

Ok... with that in mind...some feedback...

1. In Section 3, it says, "Its content consists of a root object with
a "resources" property, whose names are link relation types (as
defined by [RFC5988]), and values are Resource Objects"

I understand what you're going for with the use of link relations for
the properties names but there is some cases where it doesn't seem to
work based on the definition of the link relation. For instance, what
exactly would this mean:

  {
    "resources": {
      "self": { ... },
      "profile": { ... },
      "alternate": { ... },
      "describedby": { ... },
      // etc
    }
  }

In order to avoid any kind of possible confusion, I would actually
decouple this from link relations and just say that the property name
is an absolute URI used as a global identifier for the semantics of
the resource.... precisely as you do with the template variable
definitions under href-vars. If these happen to line up with
particular link relation names, then great. If not, that's ok too.

2. I mentioned this before in off-line direct conversation with you,
but I think it would be worthwhile to have a "profile" hint whose
value is an array of absolute URIs that identify the higher level
semantics/protocols implemented by the resource, if any. For instance,
if I wanted to say that a particular resource conformed to the
OpenSocial specification; or implemented semantics consistent with the
Atompub specification, etc. Similarly to the href-var definitions,
someone reading the hint value would have to know what the given URI
identifies in order to make use of it.

- James

---

From: Mark Nottingham <[email-masked]>
Date: Mon, 14 May 2012 20:16:10 +1000

Hi James,

> particular link relation names, then great. If not, that's ok too.

Just because some link relation types don't make sense in this context, or are poorly defined enough to be ambiguous, doesn't mean they shouldn't be here. I strongly DON'T want to create yet another instrument here unless one is really needed.

> identifies in order to make use of it.

I want to explore expressing such a thing for individual representations (because media types are pretty clumsy for this, to date). However, as I think we talked about offline, I'm resisting doing it at the 'top level' yet, because it's too easy for clients to believe that that's a "contract" that the server is guaranteeing that they'll honour.

Of course, it's still useful to say that this particular collection of resources and representations they produce will meet a certain task, but that can be done in documentation; making it machine readable is an attractive nuisance. IMO.

Cheers,

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

---

From: Martin Thomson <[email-masked]>
Date: Mon, 14 May 2012 08:43:55 -0700

>> value is an array of absolute URIs that identify the higher level
[...]
> Of course, it's still useful to say that this particular collection of resources and representations they produce will meet a certain task, but that can be done in documentation; making it machine…

The idea occurs that you might be able to provide the "hints" in the
form of link relations.  Of course, then it's turtles all the way
down...

It's tempting to think of 'hints' as the result of a HEAD request for
the resource.  Which leads then me to speculate about the nature and
usefulness of HEAD with respect to POST/PATCH/PUT/etc...  Think about
specifying Accept: headers in responses.

Then we can all sing the metadata song.  Metadata, metadata,
meta-meta-metadata...

---

From: Martin Thomson <[email-masked]>
Date: Mon, 14 May 2012 09:12:21 -0700

> While we could us a prefixing / base url approach, I'm reluctant to add that level of complexity / processing to JSON. Thoughts?

Nah.  For the sorts of cases that I'm thinking of, a href-vars can
either use the full URI or

BTW, hyphenating the names of variables is fairly toxic.

> Can you be more specific? What needs to be versioned, in your view?

That's a loaded question.  But a good one.

I've seen people up-version representations without changing the
content type.  I suspect that is what Accept-Version and Version is
used for more often than not.  But that's not the answer.

I'm thinking more of semantics.  The question of how I change the
semantics attached to a given resource is a hard one to resolve.
While the "right" answer is "never, make a new resource with the new
semantics", in reality this offers other challenges.  Especially if
you aren't actually creating URIs yourself because some fool gave away
naming rights to your clients - not that I'm bitter about that or
anything...

For instance, I'm not entirely clear on how a resource might gain an
expanded range of values of an enumerated field without signaling this
through content-type (and allowing every other PUT/POST to fail when
some proportion of the population of "widgets" don't accept the new
content-type).

Nit: Sec5, p3: s/. this/.  This/ ; s/may/could/

---

From: Michiel de Jong <[email-masked]>
Date: Mon, 14 May 2012 18:16:03 +0200

Hi,

Great to discover this! We use webfinger to discover per-user data
services like 'remoteStorage'. I am currently looking for a better
JSON format for that, especially for plonking all the information
about OAuth end-points and other details onto there, so i'm very happy
to find you are working on this. But

> JRD http://tools.ietf.org/html/rfc6415#appendix-A is a JSON document format used for discovering information about a host, service, or user.  I don't think that's orthogonal to your goals, unless I…

+1

please do integrate it with swd/webfinger and JRD, because I agree
with Mike that json-home, JRD,  swd/webfinger, and also OAuth
discovery and Google's API discovery service (which includes a way to
find where to do your OAuth for a given API, which is cool), and also
our (unfinished) personal data services spec [1] all have to do with
links to service end-points. i added a link from our spec to yours to
say we'll follow what you're doing and coordinate formats. looking
forward to see this become part of best practice for how we publish
APIs!

Cheers,
Michiel

[1] http://www.w3.org/community/unhosted/wiki/Pds

---

From: James M Snell <[email-masked]>
Date: Mon, 14 May 2012 11:03:09 -0700

On Mon, May 14, 2012 at 3:16 AM, Mark Nottingham <[email-masked]> wrote:
> [snip]

Yes, but I'm not talking about creating yet another type of
identifier, I'm talking about simply using a URI as a global
identifier. You already do it with regards to template variables, and
it would be perfectly ok if the URIs used happen to also be extension
link relations... but defining it as "link relations" in general
doesn't seem to actually solve any distinct problem here... it just
needs to be a meaningful identifier.

- James

---

From: mike amundsen <[email-masked]>
Date: Tue, 15 May 2012 10:22:18 -0400

Mark:

I've been trying to work out in my head how the messaging and client
code would look for a set up where the interaction model is expressed
as a secondary file.

1) in each response, have a link (header or in the body) that points
to the "home" document?
do you have a "recommendation" on this item? IOW, a suggested best
practice on how the client will "discover" the proper home document?
/.welknown/? in the response?, etc.?

2) use the linked home document as a guide when parsing/processing the
current representation?
not sure how to "know" what args are available for anything other than
GET, how are PUT/POST representations described?

3) use the linked home document to determine which hypermedia options
to present to the user/user-agent (for each response)?
i can see how the client code might scan the home document and present
controls to express the various templates (i.e. could be converted
into HTML.FORM elements, etc.) i assume ALL the templates would be
presented to the user/user-agent ALL the time, right? if the home
document is cached, these templates would be presented upon every
response from the server (until the caching expired, of course).

also, it seems the design includes read-only templating (URI templates
for GET), but nothing line for POST/PUT. I assume write actions would
not be provided at runtime and would only be available via
documentation that devs would consult ahead of time (before ever using
this "service") and hard-code into the client, right?

my initial reaction is that this home document design is optimized to
for use as a design-time IDL (ala WADL) instead of a run-time
interaction guide (ala HTML hypermedia).

any sample (or pseudo-code) worked up that would show using the home
document at runtime?

mca
http://amundsen.com/blog/
http://twitter.com@mamund
http://mamund.com/foaf.rdf#me

---

From: Mark Nottingham <[email-masked]>
Date: Wed, 16 May 2012 09:55:40 +1000

Hi Mike,

Thanks for the feedback. Responses below.

> 1) in each response, have a link (header or in the body) that points

Definitely not!

> /.welknown/? in the response?, etc.?

What I have in mind is that the client will be given a "starting point" -- i.e., the home page document, usually expressed as a URL, and all interaction will follow from that. For me, it makes sense if that URL is the "root" (home) document for the authority (e.g., <http://example.com/>.

For a particular use case, one *could* register a well-known URL to shorten that URL to just a hostname, but I hope that won't be the usual thing.

> 2) use the linked home document as a guide when parsing/processing the

At this point, I'm reluctant to define this. The Web works because media types *are* effectively guides to parsing representations. 

That said, I want to make the representation types capable of carrying more data than just the media type (such as a profile), but I'm keenly aware that doing so will encourage people to do things like put schema in there, so they can do "data binding" to objects. IMO that's asking for trouble. 

There might be some useful cases for that (e.g., doing QA on the API, having an intermediary do something with it), but all of the experience we've had with "data binding" has made be extremely wary of doing this without a lot of consideration.

I'm fine with describing (again, as a hint) the expected semantics of the document; if the media type covers this, great, if not, that's where I'm thinking profiles might help. It's describing the syntax where it gets sticky.

> GET, how are PUT/POST representations described?

The assumed convention is that what you can GET you can PUT (assuming PUT is allowed). The accept-post hint covers POSTs. 

> to present to the user/user-agent (for each response)?

Please explain?

> presented to the user/user-agent ALL the time, right?

That's up to the client. 

> if the home

Yes. Hopefully, it will be (and the draft encourages this).

> for GET), but nothing line for POST/PUT.

What caused you to make that assumption?

> I assume write actions would

I'm not sure what you mean by "write actions." Do you mean PUT, or something more fine-grained?

> interaction guide (ala HTML hypermedia).

Can you be more specific? On its own, that's not a helpful comment.

> any sample (or pseudo-code) worked up that would show using the home

Am working on it...

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

---

From: mike amundsen <[email-masked]>
Date: Tue, 15 May 2012 21:56:30 -0400

since i forgot to say it in my first comment; thanks for offering this up.
i am looking forward to learning more about it.

so, my follow up inline....

> > 1) in each response, have a link (header or in the body) that points
_when_ should a client retrieve this document? at design-time? at run-time
on the _first_ call to the domain space? and then each time the caching
expires after that?

> What I have in mind is that the client will be given a "starting point" --
> i.e., the home page document, usually expressed as a URL, and all
> interaction will follow from that. For me, it makes sense if that URL is
> the "root" (home) document for the authority (e.g., <http://example.com/>.
>
> For a particular use case, one *could* register a well-known URL to
> shorten that URL to just a hostname, but I hope that won't be the usual
> thing.
>
so, a client should be coded to pick up this document form a pre-determined
location (i.e. the service documentation will publish a URI for the
document.).

> At this point, I'm reluctant to define this. The Web works because media
> types *are* effectively guides to parsing representations.
>
media types *are* guides to parsing. this _is_ a media type, right? this is
the guide to parsing, right?

>
> That said, I want to make the representation types capable of carrying
> more data than just the media type (such as a profile), but I'm keenly
> aware that doing so will encourage people to do things like put schema in
> there, so they can do "data binding" to objects. IMO that's asking for
> trouble.
>
so you want to "discourage" certain information from appearing in this
document, rigiht (i.e. no schema should appear, no binding of UI to data
elements should appear, what else)?

>
> There might be some useful cases for that (e.g., doing QA on the API,
> having an intermediary do something with it), but all of the experience
> we've had with "data binding" has made be extremely wary of doing this
> without a lot of consideration.
>
can you give an example of how this document could be used in QA?

>
> I'm fine with describing (again, as a hint) the expected semantics of the
> document; if the media type covers this, great, if not, that's where I'm
> thinking profiles might help. It's describing the syntax where it gets
> sticky.
>
i;m not clear on this answer. are you saying "the media type" === not this
document? what expected semantics to you have in mind here?

> The assumed convention is that what you can GET you can PUT (assuming PUT
> is allowed). The accept-post hint covers POSTs.
>
i can see (using URI templates how GET requests can be composed using
information in this document. i can't see details on how to compose a PUT
using the example. am i missing something? are clients expected to parse
the URI template vars and use that to compose a body for PUT/POST?

> > to present to the user/user-agent (for each response)?
i assume that the document will contain several (possibly dozens) of
Resource Objects. i assume that the client application would consume this
document and then use it to build up a UI that shows each of the Resource
Objects along with the possible arguments. Users will then select the one
they like, fill in the details and execute the request. am i wrong in this?

> > presented to the user/user-agent ALL the time, right?
Yep, i understand it's up to the client. what i am unclear on is _how_ the
client will decide which items to "show" is this done by hard-coding the
client to only show selected controls at certain times (determined by the
client)? or is the decision on which Object Resources to render decided at
run-time by the client? and if it's decided at runtime, how is that
decision made?

> What caused you to make that assumption?
i assumed that the "href-template" and "href-vars" describe the details
on composing a URI used for GET (possibly DELETE). i assumed the home
document does not contain similar descriptions for composing a body for
PUT/POST since i could not find "body-template" and "body-vars" elements in
your design.

> something more fine-grained?
by "write actions" i mean the unsafe HTTP methods POST & PUT. this goes
back to my previous follow up. while i see details in your document on
composing URIs, i don't see details on composing bodies. i see the it's
possible to *tell* clients a PUT is possible. i don't see that it is
possible to tell clients what a valid PUT body looks like. i assumed, then,
that information would be in written documentation that the client
developer would consult when coding the client.

> Can you be more specific? On its own, that's not a helpful comment.
my current understanding of your I-D is that it desctibes a static resource
which contains details on a "context-free" list of possible actions on
Object Resources. this looks to me very much like WADL/WSDL. alternatively,
designs like Mike Kelly's HAL or my Collection+JSON describe dynamic
representations that contain lists of "context-bound" possible actions
within the response itself (similar to HTML). does this make sense? is it
an accurate characterization of your I-D?

> > any sample (or pseudo-code) worked up that would show using the home
cool. keep me posted. if you'd like, i'd be happy to attempt to build
something using this desgin once you think it is (and I am) ready<g>.

---

From: Mark Nottingham <[email-masked]>
Date: Wed, 16 May 2012 14:30:28 +1000

On 16/05/2012, at 11:56 AM, mike amundsen wrote:

> since i forgot to say it in my first comment; thanks for offering this up. i am looking forward to learning more about it.

Thanks.

> _when_ should a client retrieve this document? at design-time? at run-time on the _first_ call to the domain space? and then each time the caching expires after that? 

It's up to the client; they just need to use a fresh copy when they use it. The simplest (but least efficient) design would be to fetch it before every request; next would be to fetch-and-cache upon first use. However, some clients might want to have a thread/process/task keeping a copy fresh in the "background" as long as they're interested in that service.

> so, a client should be coded to pick up this document form a pre-determined location (i.e. the service documentation will publish a URI for the document.). 

Yes. Just as I go to http://www.amazon.com/ to buy [insert most products here].

>> media types *are* guides to parsing. this _is_ a media type, right? this is the guide to parsing, right? 
>> 
> so you want to "discourage" certain information from appearing in this document, rigiht (i.e. no schema should appear, no binding of UI to data elements should appear, what else)? 

Possibly. I'd say that I want to vet what gets in very carefully, because in the past people have gone so far off the rails with this kind of format, and once it's out in the open, people are going to try to bend it to fit those patterns / tools / expectations.

> can you give an example of how this document could be used in QA?  

Well, effectively QA is a client, and it has to be able to consume the API. Beyond that, you may want to annotate the document with QA-specific information (e.g., "I expect THIS resource/representation to meet THOSE tests").

> i;m not clear on this answer. are you saying "the media type" === not this document? what expected semantics to you have in mind here?

I mean the syntax/semantics of the request and responses representations send in interactions driven by this format. So, "the media type" is their media type(s).

> i can see (using URI templates how GET requests can be composed using information in this document. i can't see details on how to compose a PUT using the example. am i missing something? are clients expected to parse the URI template vars and use that to compose a body for PUT/POST? 

See below.

> i assume that the document will contain several (possibly dozens) of Resource Objects. i assume that the client application would consume this document and then use it to build up a UI that shows each of the Resource Objects along with the possible arguments. Users will then select the one they like, fill in the details and execute the request. am i wrong in this?

That's one possible use of it, yes. 

> Yep, i understand it's up to the client. what i am unclear on is _how_ the client will decide which items to "show" is this done by hard-coding the client to only show selected controls at certain times (determined by the client)? or is the decision on which Object Resources to render decided at run-time by the client? and if it's decided at runtime, how is that decision made? 

I'm circumspect about use of the term "show" here, but pushing on, the document certainly can/should be "personalised" to indicate what resources, etc. are available to the client. Of course, actually attempting interaction gives authoritative information, and interacting with resources might expose further information that wasn't available in the home document.

> i assumed that the "href-template" and "href-vars" describe the details on composing a URI used for GET (possibly DELETE). i assumed the home document does not contain similar descriptions for composing a body for PUT/POST since i could not find "body-template" and "body-vars" elements in your design.   

I'm purposefully punting on body / format constraints for the time being, but will get to it.

> by "write actions" i mean the unsafe HTTP methods POST & PUT. this goes back to my previous follow up. while i see details in your document on composing URIs, i don't see details on composing bodies. i see the it's possible to *tell* clients a PUT is possible. i don't see that it is possible to tell clients what a valid PUT body looks like. i assumed, then, that information would be in written documentation that the client developer would consult when coding the client.

OK, see above.

> my current understanding of your I-D is that it desctibes a static resource which contains details on a "context-free" list of possible actions on Object Resources. this looks to me very much like WADL/WSDL. alternatively, designs like Mike Kelly's HAL or my Collection+JSON describe dynamic representations that contain lists of "context-bound" possible actions within the response itself (similar to HTML). does this make sense? is it an accurate characterization of your I-D?    

No. It's very much the opposite; e.g., from the draft:

>    In contrast, a "follow your nose" API advertises the resources
>    available to clients using link relations [RFC5988] and the formats
>    they support using internet media types [RFC4288].  A client can then
>    decide - at "run time" - which resources to interact with based upon
>    its capabilities (as described by link relations), and the server can
>    safely add new resources and formats without disturbing clients that
>    are not yet aware of them.
> 
>    As such, the client needs to be able to discover this information
>    quickly and efficiently use it to interact with the server.  Just as
>    with a human-targeted "home page" for a site, we can create a "home
>    document" for a HTTP API (often, at the same URI, found through
>    server-driven content negotiation) that describes it to non-browser
>    clients.

and:

>    o  Home documents can be personalised, just as "normal" home pages
>       can.  For example, you might advertise different URIs, and/or
>       different kinds of link relations, depending on the client's
>       identity.

and:

>    Note that the home document is a "living" document; it does not
>    represent a "contract", but rather is expected to be inspected before
>    each interaction.  In particular, links from the home document MUST
>    NOT be assumed to be valid beyond the freshness lifetime of the home
>    document, as per HTTP's caching model [RFC2616].

I'm happy to expand upon this further in the draft, but I thought I'd already used a fairly large sledgehammer / clue-by-four.

> cool. keep me posted. if you'd like, i'd be happy to attempt to build something using this desgin once you think it is (and I am) ready<g>. 

Great; will do.

---

From: mike amundsen <[email-masked]>
Date: Wed, 16 May 2012 08:42:56 -0400

Mark:

OK, I think I have a general sense of what you're working on here. check me:
- clients will be coded to "start" w/ this document (and keep a fresh copy
on hand while interacting w/ the related service)
- while the document currently includes URI templates to describe valid GET
requests, there are currently no body templates to describe valid PUT/POST
requests
- this document is not the source of semantic interactions for
client-server interaction (that will still be in the primary response
representations from the service); it is merely an additional descriptor
document to aide in knowing what transitions are possible and (in some
cases) how to compose a valid transition request
- the document will not contain schema, data bindings or other similar
information

That pretty close at least?

Finally, while you have quite a bit of prose saying this document is not
static, "the client can decide at run-time", "follow your nose", etc. I
don't yet see details on _how_ this document could be used at run-time to
"lead" clients through a set of state transitions; not sure what clients
will "follow" in this document. For now I will assume this is due to a
limitation on my part and will wait for some additional drafts and possibly
some examples/pseudo-code to help me out.

Thanks.

mca

On Wed, May 16, 2012 at 12:30 AM, Mark Nottingham <[email-masked]> wrote:

> > since i forgot to say it in my first comment; thanks for offering this
> up. i am looking forward to learning more about it.
>
> Thanks.
>
>
> > _when_ should a client retrieve this document? at design-time? at
> run-time on the _first_ call to the domain space? and then each time the
> caching expires after that?
>
> It's up to the client; they just need to use a fresh copy when they use
> it. The simplest (but least efficient) design would be to fetch it before
> every request; next would be to fetch-and-cache upon first use. However,
> some clients might want to have a thread/process/task keeping a copy fresh
> in the "background" as long as they're interested in that service.
>
>
> >> What I have in mind is that the client will be given a "starting point"
> -- i.e., the home page document, usually expressed as a URL, and all
> > so, a client should be coded to pick up this document form a
> pre-determined location (i.e. the service documentation will publish a URI
> for the document.).
>
> >> At this point, I'm reluctant to define this. The Web works because
> media types *are* effectively guides to parsing representations.
> Possibly. I'd say that I want to vet what gets in very carefully, because
> in the past people have gone so far off the rails with this kind of format,
> and once it's out in the open, people are going to try to bend it to fit
> those patterns / tools / expectations.
>
>
> Well, effectively QA is a client, and it has to be able to consume the
> API. Beyond that, you may want to annotate the document with QA-specific
> information (e.g., "I expect THIS resource/representation to meet THOSE
> tests").
>
>
> >> I'm fine with describing (again, as a hint) the expected semantics of
> the document; if the media type covers this, great, if not, that's where
> I'm thinking profiles might help. It's describing the syntax where it gets
> sticky.
> >
> > i;m not clear on this answer. are you saying "the media type" === not
> this document? what expected semantics to you have in mind here?
>
> I mean the syntax/semantics of the request and responses representations
> send in interactions driven by this format. So, "the media type" is their
> media type(s).
>
>
> >> The assumed convention is that what you can GET you can PUT (assuming
> PUT is allowed). The accept-post hint covers POSTs.
> >
> > Yep, i understand it's up to the client. what i am unclear on is _how_
> the client will decide which items to "show" is this done by hard-coding
> the client to only show selected controls at certain times (determined by
> the client)? or is the decision on which Object Resources to render decided
> at run-time by the client? and if it's decided at runtime, how is that
> decision made?
>
> I'm circumspect about use of the term "show" here, but pushing on, the
> document certainly can/should be "personalised" to indicate what resources,
> etc. are available to the client. Of course, actually attempting
> interaction gives authoritative information, and interacting with resources
> might expose further information that wasn't available in the home document.
>
>
> > my current understanding of your I-D is that it desctibes a static
> resource which contains details on a "context-free" list of possible
> actions on Object Resources. this looks to me very much like WADL/WSDL.
> alternatively, designs like Mike Kelly's HAL or my Collection+JSON describe
> dynamic representations that contain lists of "context-bound" possible
> actions within the response itself (similar to HTML). does this make sense?
> is it an accurate characterization of your I-D?
>
> I'm happy to expand upon this further in the draft, but I thought I'd
> already used a fairly large sledgehammer / clue-by-four.
>
>

---

From: Graham Klyne <[email-masked]>
Date: Wed, 16 May 2012 07:25:48 +0100

> code would look for a set up where the interaction model is expressed

Mike,

I'm not sure if this will help, but...

There's a project I've been working on that uses a similar idea ... and I would 
be happy to use Mark's format if it looks likely to get a community following 
... there's a rough description of a web API I've proposed at 
http://www.wf4ever-project.org/wiki/display/docs/RO+checklist+evaluation+API.

Look at the section "Web API", and ignore the details of the application.

The sequence is:
1. retrieve "home" ("service") document (assumes knowledge of service URI)
2. extract the URI template (assumes knowledge of common document format and 
link relation type for the desired service)
3. form URI by combining URI template with parameter values (assumes knowledge 
of the parameters associated with the service, and their names as used in the 
template)
4. perform standard HTTP operation on the resulting URI, and interpret the result.

The intent is to loosen the coupling between client and service, giving the 
service greater freedom to evolve without requiring updating of the client (and 
vice versa).

It's the combination of the home document (or service document) as a 
well-understood format and the URI template that's the key enabling feature, 
IMO.  Given the URI of the service, and knowledge of the standard formats used, 
it allows a client to construct a URI to access an application-defined resource.

HTH.

#g
--

> On Thu, May 10, 2012 at 12:28 AM, Mark Nottingham<[email-masked]>  wrote: