Question

I’m trying to create a self documenting python web service.

My Situation:

I’ve got an object accessible via RESTful python web service.

http://foo.com/api/monkey

And, what I’d like to do is if

1. there’s an error during a call to http://foo.com/api/monkey like http://foo.com/api/monkey/get was called without “&monkey_id={some number}”

   *or*

2. the web service call is made specifcally to http://foo.com/api/monkey/help

then i want it to return the formatted html epydoc output for that object (dynamically).

I’ve reviewed cornice, but its a pain because I don’t want to use Pyramid. I really don’t want to be coupled to any particular web framework to be able to do this.

My question is this: Is what I want to do, with epydoc, possible?

Answer 1

The first use case (“there’s an error during a call”) is poorly-defined. 404 errors, for example, don’t result in help pages, they’re perfectly ordinary.

A http://foo.com/api/bad/path/get request can’t figure out which help page to send, since it didn’t make a monkey request.

Also, putting /get on your path is not really very RESTful at all. Doing /monkey/get/monkey_id={some number} is considered bad form. You should consider doing /monkey/{some mnumber}/. That’s considered RESTful.

There are very, very few situations where you’ll want to show help.

However, there may be some kinds of error handling where you do want to show help.
For these you should provide a 301 redirect to http://foo.com/api/monkey/help instead of some other error page.

Your ordinary http://foo.com/api/monkey/help URL’s should be handled by Apache (or nginx or lighttpd or whatever your web server is) to redirect to the static Epydoc-produced HTML files.