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 <
> [email protected] <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 [email protected]<javascript:>
>> To unsubscribe from this group, send email to
>> [email protected] <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 [email protected] <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 [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.
