Hey masklinn, I'm totally receptive to constructive criticism like this, so can you make it even more constructive? :)
I've seen many "RESTful" APIs with this structure:
GET / => index
GET /<id> => show
GET /?someparams=someattrs => filtered index
POST / (with encoded params) => create
PUT /<id> (with encoded params) => update
DELETE /<id> => delete
If you made a Rails scaffold, and got rid of any of the POST, PUT, and DELETE actions, and then added some basic filtering to GET "/", you would have a nearly identical API as generated and documented by Restivus.
> Hey masklinn, I'm totally receptive to constructive criticism like this, so can you make it even more constructive? :)
Sure, just ask, I'll answer if I can.
> I've seen many "RESTful" APIs with this structure:
Yes, and that API is not even remotely RESTful according to Fielding (whom you may or may not agree with, but he's the guy who thought up REST and coined the acronym). It can be a fine API, but not RESTful: it's not hypertext-driven, instead it's a (hierarchically organized) set of function calls mapped onto HTTP.
> In any context, documenting every function is good practice.
If your API is procedural (is RPC), then yes, procedures being your core abstractions that's what you document.
But REST is not procedural, the core RESTful abstraction is the resource and it is that resource which provides state transitions from itself (to itself or to other resources). In HTTP these transitions are a triplet of (method, URI[, body]) but that's incidental.
Because the core abstraction of REST is the resource, resource types (or media types) is what you document, and the possible transitions from a media type are documented as part of that media type (more precisely, the media type's documentation indicates what the transition hookpoints are — for instance in HTML they're <link>, <a> and <form> — and what the semantics of those hookpoints are relative to the resource — if any).
To clarify, I have absolutely no issue with your goal of documenting your API and every endpoint of your API, I just take issue with your claim of documenting RESTful APIs when the very structure of your tool and production preclude any possibility of RESTfulness.
Masklinn was just stating that an API based on 'functions' is inherently not a REST API, but instead RPC. The documentation sentiment is sound, but your terminology was off.
I've seen many "RESTful" APIs with this structure:
GET / => index
GET /<id> => show
GET /?someparams=someattrs => filtered index
POST / (with encoded params) => create
PUT /<id> (with encoded params) => update
DELETE /<id> => delete
If you made a Rails scaffold, and got rid of any of the POST, PUT, and DELETE actions, and then added some basic filtering to GET "/", you would have a nearly identical API as generated and documented by Restivus.