Thank you for great answers! It is true that RESTful app should be self-documented. Anyway, if new user (human), which probably are new customer wan't create own client application, (s)he definitely needs some textual documentation about server-application, even if (s)he understand REST API model. For example documentation for each resources, why are they there and what purpose... My purpose now is to satisfy this section. But,, Maybe I didn't understand fully REST deeper purpose. I think most of ("hobby-users") didn't, because I tried to find pure RESTful style expressjs application, and I didn't found any! At least in my eyes those didn't look pure RESTful.. If you know some simple example but pure RESTful, please let me know. And I still believe that express routes can be used for documentation source, but definitely routes needs more associated meta information and I wonder how it would be best implement..At least routes contains all possible URL paths :) .
Cheers, Jussi sunnuntai, 28. heinäkuuta 2013 17.17.12 UTC+3 Kevin Swiber kirjoitti: > > 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 < > diamon...@users.sourceforge.net <javascript:>> 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 nod...@googlegroups.com<javascript:> >> To unsubscribe from this group, send email to >> nodejs+un...@googlegroups.com <javascript:> >> 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 nodejs+un...@googlegroups.com <javascript:>. >> 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 nodejs@googlegroups.com To unsubscribe from this group, send email to nodejs+unsubscr...@googlegroups.com 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 nodejs+unsubscr...@googlegroups.com. For more options, visit https://groups.google.com/groups/opt_out.