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

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



On Thu, May 10, 2012 at 12:28 AM, Mark Nottingham <mnot@...> wrote: _______________________________________________
apps-discuss mailing list
apps-discuss@...
https://www.ietf.org/mailman/listinfo/apps-discuss