Link Details

Link 750577 thumbnail
User 121174 avatar

By jd44165
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.
  • 6
  • 0
  • 744
  • 646
User 226303 avatar

devdanke replied ago:

0 votes Vote down Vote up Reply

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

Add your comment

Html tags not supported. Reply is editable for 5 minutes. Use [code lang="java|ruby|sql|css|xml"][/code] to post code snippets.

Upvoters (6)

Downvoters (0)

    Apache Hadoop
    Written by: Piotr Krewski
    Featured Refcardz: Top Refcardz:
    1. Play
    2. Akka
    3. Design Patterns
    4. OO JS
    5. Cont. Delivery
    1. Play
    2. Java Performance
    3. Akka
    4. REST
    5. Java