Hi Dave,
Dave Tkaczyk wrote:
> Hi,
>
>
>
> I have a question that I hope you can help me with. There doesn’t seem
> to be a standard way of documenting how a REST service works - beyond
> the obvious http methods. We will be producing and consuming xml. Is
> there a standard way to document the use of the xml that we will be
> producing and consuming? Our particular concerns are with the content
> of the xml, the cardinality of sub-elements, data type, and
> required/optional attributes and elements.
>
I think you need to reference the XML Schema in such cases.
>
>
> I’ve looked at Amazon’s S3 documentation as an example. They do a great
> job of documenting their service from the stand point of http methods,
> but there doesn’t seem to be any documentation on the entities that will
> be shared across the wire. They seem to rely solely on their examples
> to get the point across.
>
>
>
> Also, we are trying to keep this as “lite” as possible, so have ruled
> out maintaining a WADL as it feels too much like a SOAP WSDL – albeit,
> simpler to figure out. Is DTD an option? If so do you have any examples
> of it in action? Do people use UML for this purpose?
>
IMHO WADL is rather good as a framework for documentation purposes, see
Yahoo's usage using a style sheet to generate HTML from the WADL:
http://developer.yahoo.com/search/web/V1/webSearch.html
http://www.mnot.net/webdesc/YahooSearch.html
In the following notice the reference to the XSD and embedding of the XSD:
http://www.mnot.net/webdesc/YahooSearch.html#representations
Hope this helps,
Paul.
>
>
> Am I missing something? Any advice or examples that you could provide
> would be very much appreciated.
>
>
>
> Thanks,
>
> Dave
>
>
>
>
>
>
> Confidentiality Notice: This email message is covered by the
> Electronic Communications Privacy Act, 18 U.S.C. §2510-2521 and is
> legally privileged. Unauthorized review, use, disclosure or
> distribution is strictly prohibited. If you are not the intended
> recipient, please contact /Dave.Tkaczyk_at_innerwireless.com/ and
> destroy all copies of the original message. Thank you.
--
| ? + ? = To question
----------------\
Paul Sandoz
x38109
+33-4-76188109