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

[Mark Nottingham <[e-mail]>]

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.


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

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


> > 2) use the linked home document as a guide when parsing/processing the
> > current representation?
> 
>> 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)? 

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.


>> 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?  

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


> > not sure how to "know" what args are available for anything other than
> > 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.
> 
> 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.


> > 3) use the linked home document to determine which hypermedia options
> > to present to the user/user-agent (for each response)?
> 
>> Please explain?
> 
> 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. 


> > 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?
> 
>> That's up to the client.
> 
> 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.


> > also, it seems the design includes read-only templating (URI templates
> > for GET), but nothing line for POST/PUT.
> 
>> 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.   

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


> > 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?
> 
>> I'm not sure what you mean by "write actions." Do you mean PUT, or 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.

OK, see above.


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

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.


> > any sample (or pseudo-code) worked up that would show using the home
> > document at runtime?
> 
>> Am working on it...
> 
> 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.



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