Hi,
one question is what you want to document. Is it enough for you to
describe the structure of requests/responses, or do you also want to
document which resources and which methods on resources are available.
IMHO with WADL you can describe how some RESTful WebService works very
well, as all important concepts (resources, methods, representations)
are provided.
Cheers,
Martin
On Thu, 2008-04-24 at 09:20 -0500, 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’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?
>
>
>
> 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.