This sort of discussion ("What is REST?") might be better on the API Craft
Google Group. See: https://groups.google.com/forum/#!forum/api-craft
That's where my REST cronies and I hang out. It's very welcoming.
I work in the REST API space and have been using Node almost exclusively
for Web APIs.
In regards to HATEOAS: Hypermedia has not hit the mainstream. Hypermedia
nerds, such as myself, have not provided a great documentation story.
We're working on it. If you still need to build clients, you still need
documentation. Media type documentation often does not get into the
application semantics.
For the mainstream acceptance of the meaning of REST, there's WADL for
describing APIs (
http://en.wikipedia.org/wiki/Web_Application_Description_Language).
You can use something like WADL stylesheets to generate HTML documentation (
https://github.com/mnot/wadl_stylesheets/).
The issue with generating docs from Express routes is that there's just not
enough meta information associated with a route. In theory, it might not
take much to generate docs out of comments associated with routes (a la
JSDoc). That might be something worth exploring.
Cheers,
--
Kevin Swiber
Projects: https://github.com/kevinswiber
Twitter: @kevinswiber
On Sun, Jul 28, 2013 at 12:01 AM, Austin William Wright <
[email protected]> wrote:
> I don't think this should really be necessary: The whole point of REST is
> that it's self-documenting, that any old user agent (like a web browser,
> but also robots) should be able to pull up the endpoint and start
> interacting with it.. This is typically done with HTML forms and hyperlinks
> (and actually, hyperlinks are mandantory -- that's what the HATEOAS
> component of REST is all about: Hypermedia as the Engine of Application
> State).
>
> Some common problems are nicely detailed at <
> http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven>:
>
> There's two important points here, which I'll quote:
>
> - 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.]*
> - 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]*.
>
> The gist here is that you shouldn't have to document how to use the
> service, beyond knowing consumption of the media types that are returned.
> If clients need to know out-of-bound information like how to form a URI
> (instead of following a server-provided hyperlink or form), then what
> you're creating isn't RESTful.
>
> For more machine-friendly endpoints, you can use Content-Type negotiation,
> JSON Hyper-Schema, and the "profile" and "describedby" link relations.
>
> On Wednesday, July 24, 2013 12:23:47 AM UTC-7, JVA wrote:
>>
>> Hi all,
>>
>> I'm wondering if anyone has tried to generate REST api documentation
>> (html) based directly to express routes ?
>> I would be also very interested to hear any comments related how to
>> create nice & entire REST api documentation.
>> I've tried find perfect solution but didn't find yet.
>>
>> My *requirements*:
>> -MD support
>> -html UI
>> -entire api doc, (all expressjs routes )
>> -mongoose schema documentation support directly from schema
>> -(nice to have) possible to generate single file doc (e.g. pdf/doc/html)
>>
>> What I'm tried already (bold words is most critical thing why I didn't
>> select that library) :
>>
>> *apidoc* <https://npmjs.org/package/apidoc>
>> + MD support
>> + nice UI
>> + several comment tag supports
>> + pluggable
>> + generate html -> "offline usage"
>> + versioning
>> -* no TAC* (table of content)
>> *this might be possible to do with pluggin?
>> - needs a lot of comment tags to get good enought doc
>> - depends on comments how perfect document are
>> - If mongoose is used in back-end there is no easy way for *document
>> schemas *(related to REST-api)
>> *this can be done with pluggin.
>>
>> *express-api-docs* <https://npmjs.org/package/express-api-docs>
>> +routes based
>> *-no REST style*
>> *
>> *
>> Is there any other libraries ? Currently this apidoc seems to be best
>> solution for me,
>> but needs "a lot of" job to get all requirements fulfilled, but there
>> might be also several limitations...
>>
>> Best Regards,
>> Jussi
>>
> --
> --
> Job Board: http://jobs.nodejs.org/
> Posting guidelines:
> https://github.com/joyent/node/wiki/Mailing-List-Posting-Guidelines
> You received this message because you are subscribed to the Google
> Groups "nodejs" group.
> To post to this group, send email to [email protected]
> To unsubscribe from this group, send email to
> [email protected]
> For more options, visit this group at
> http://groups.google.com/group/nodejs?hl=en?hl=en
>
> ---
> You received this message because you are subscribed to the Google Groups
> "nodejs" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to [email protected].
> For more options, visit https://groups.google.com/groups/opt_out.
>
>
>
--
--
Job Board: http://jobs.nodejs.org/
Posting guidelines:
https://github.com/joyent/node/wiki/Mailing-List-Posting-Guidelines
You received this message because you are subscribed to the Google
Groups "nodejs" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/nodejs?hl=en?hl=en
---
You received this message because you are subscribed to the Google Groups
"nodejs" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
For more options, visit https://groups.google.com/groups/opt_out.
