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

Hi Mike,

Thanks for the feedback. Responses below.


On 16/05/2012, at 12:22 AM, mike amundsen wrote:

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

Definitely not!


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


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

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.


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


> 3) use the linked home document to determine which hypermedia options
> to present to the user/user-agent (for each response)?

Please explain?


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


> if the home
> document is cached, these templates would be presented upon every
> response from the server (until the caching expired, of course).

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


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


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


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


Am working on it...

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




_______________________________________________
apps-discuss mailing list
apps-discuss@...
https://www.ietf.org/mailman/listinfo/apps-discuss