Standard methods for documenting a RESTful API

Question

I'm writing a specification for a RESTful API for a new internal web service. It's not hugely long and fairly simple, but even so, it's my first time using strict REST (as opposed to cheating for practical reasons - avoiding PUT and DELETE because they're a pain in PHP, and so on). I was wondering if there were any standard methods or best practices for documenting a REST interface? I want the rest of the team to understand it at a glance, and for anyone that wants to write a client to be able to do so without understanding the underlying code.

Answer 1

Sure, REST APIs should ideally use HATEOAS and be hypertext driven (with heavy use of media types), but also having simple human-friendly documentation for developers to work off of is helpful.

Some specific tools that are helpful for generating documentation like this:

• Swagger
  • An open spec for describing REST APIs [ github ]
  • Tools for auto-generating
    • Documentation
    • Code for your API
  • Donated to the OpenAPI initiative and renamed OpenAPI in 2015
• Mashery
  • An open source project [ github ]
  • Tools for generating
    • Documentation
    • An exploration interface for your API
• Apiary and API Blueprint
  • Write the API description in a DSL within markdown
  • Tools for auto-generating
    • Documentation
    • Mock server
  • Seems to be focused on ruby+mac devs
• RAML
  • A spec for describing REST APIs [ github ]
• WADL
  • A spec for writing discoverable API docs with XML
  • Some discussion comparing WSDL and WADL
• APIgee
  • A commercial product with some documentation features
• 3scale
  • A commercial product with some documentation features
• miredot
  • Commercial REST API documentation generator
  • Java specific