RESTful API design + documentation tools?
- Hello --
I'm working on a web-enabled API to some of our server functions, and
have been looking around at existing APIs for inspiration, both in
implementation design and in how the APIs are released to the
developer community. There are some very nice ones out there, all of
which differ slightly in their RESTfulness, implementation and
- plus Google, Yahoo, etc.
I'd like to see whether we can use this approach, but have realized
that I'm lacking tools that help me create a RESTful API.
In particular, it seems clear that one of the biggest challenges in
REST is figuring out how to think about your functionality in terms
of resources / documents rather than methods, and building your API
around those concepts plus HTTP verbs. But if you look at the above
examples, they all have structured documentation but it is all
slightly different in terms of what it describes (arguments,
authentication, example response, error codes, etc). I was wondering
whether you used any particular tools (or had recommendations) for
designing and documentating this type of API in the form of developer
documentation that would be suitable for sending out to folks for
comments. I'm thinking of something like JavaDoc, but essentially for
a web-based API only (i.e. no implementation details).
In the absence of such tools, I'll just write it straight in HTML,
but it seems like a structured approach would help both from a design
and a documentation standpoint, so I thought I'd see if there were
any suggestions for this. Note that these could be embedded in source
code as well (e.g. using @annotations in Java/Python to indicate
whether a given object is PUTtable). But I haven't seen anything like
Thanks in advance for your time.