This week's book giveaway is in the Kotlin forum.
We're giving away four copies of Kotlin in Action and have Dmitry Jemerov & Svetlana Isakova on-line!
See this thread for details.
Win a copy of Kotlin in Action this week in the Kotlin forum!
  • Post Reply Bookmark Topic Watch Topic
  • New Topic

How do you like REST API documentation to look?  RSS feed

 
Jonathan Sachs
Greenhorn
Posts: 16
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I’m tasked with designing a format for on-line documentation of several REST APIs. I’m supposed to use the “new style” format supported by documentation tools like Swagger, as opposed to something modeled after C library documentation or Javadoc. I'm told that this is the de facto standard for modern API documentation, and it is what developers who use REST APIs expect and like.

I've examined over a dozen REST API documentation sets published by leading web businesses like Twitter, Google, and LinkedIn. They don't seem to have anything in common that would help me define what the "new style" of API documentation is. Some of them do things I’d never do, such as providing examples of how to use the API but no formal description of the request and response elements. That undercuts whatever authority they have as examples of good practice.

I’m looking for some independent input here. What do you, as a consumer of REST API documentation, expect and want? What sites can you point to as models to emulate, and why?
 
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!