Loading ...
Sorry, an error occurred while loading the content.

RESTful API design + documentation tools?

Expand Messages
  • felciano
    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
    Message 1 of 1 , Jun 1, 2005
    • 0 Attachment
      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
      documentation:

      - http://www.43things.com/about/view/web_service_api
      - http://textamerica.com/api.aspx
      - http://code.blogspot.com/archives/atom-docs.html
      - http://www.backpackit.com/api/
      - 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
      this yet...

      Thanks in advance for your time.

      Ramon
    Your message has been successfully submitted and would be delivered to recipients shortly.