It's a quick and dirty Ruby gem that exposes CSV data with RESTful endpoints (read-only for now) with a pretty docs page that automagically gives you:
1. Example code
2. Documentation for every single function
3. Human readable requests/responses
Automatic generation of client SDKs is a big TODO.
If you're still interested, check out http://github.com/adelevie/restivus.
Reading your docs.erb, the core structure (of the docs, and of the APIs it will document) seems to be along the lines of URL > Verbs > Content.
According to Fielding, you probably shouldn't call it REST or RESTful, because it's not[0]:
> A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]
and
> A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. [Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC's functional coupling].
That your documentation is function-driven:
> Documentation for every single function
also hints at this being RPC-over-HTTP more than REST (which is fine, as long as it's called correctly).
[0] http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...
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.
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.
> also hints at this being RPC-over-HTTP more than REST (which is fine, as long as it's called correctly).
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.