|
»
« Return to Thread: [apps-discuss] FYI: "home" document format for APIs
Re: [apps-discuss] FYI: "home" document format for APIs
by Graham Klyne-2
::
Rate this Message:
On 15/05/2012 15:22, 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.
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
--
>
> 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:
>> 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/
>>
>>
>>
>> _______________________________________________
>> apps-discuss mailing list
>> apps-discuss@...
>> https://www.ietf.org/mailman/listinfo/apps-discuss
> _______________________________________________
> apps-discuss mailing list
> apps-discuss@...
> https://www.ietf.org/mailman/listinfo/apps-discuss
>
_______________________________________________
apps-discuss mailing list
apps-discuss@...
https://www.ietf.org/mailman/listinfo/apps-discuss
> 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.
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
--
>
> 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:
>> 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/
>>
>>
>>
>> _______________________________________________
>> apps-discuss mailing list
>> apps-discuss@...
>> https://www.ietf.org/mailman/listinfo/apps-discuss
> _______________________________________________
> apps-discuss mailing list
> apps-discuss@...
> https://www.ietf.org/mailman/listinfo/apps-discuss
>
_______________________________________________
apps-discuss mailing list
apps-discuss@...
https://www.ietf.org/mailman/listinfo/apps-discuss
« Return to Thread: [apps-discuss] FYI: "home" document format for APIs
| Free embeddable forum powered by Nabble | Forum Help |
