By jd44165
via smartjava.org
Published: Feb 24 2012 / 12:05
Some people believe that REST services are fully self-documenting. Although this is true to a degree, not everything is self-explanatory. In this article I show a couple of pointers and elements that you should take into consideration when creating and documenting REST based APIs and services.
Comments
devdanke replied ago:
Great question! They certainly need documentation. A nice simple convension for documenting REST services would be useful to many developers. [I agree, WADL is too formal and cumbersome (to much like the horrific WSDL).]
Two of the more popular public REST APIs are from Google and Amazon. They're document and they're documented differently.
There's a good chance someone will invent a nice simple way to document REST APIs, but only if IBM, Microsoft, and Oracle can be kept out of it. These companies (and their complexity loving engineers) create the worst, most impractical, and painful standards (e.g. D/COM, SOAP, and EJB).
Voters For This Link (6)
Voters Against This Link (0)