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

[mike amundsen <[e-mail]>]

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
http://amundsen.com/blog/
http://twitter.com@mamund
http://mamund.com/foaf.rdf#me




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

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