Rewrite of the Readme #62
Conversation
There was a problem hiding this comment.
I think you did great, this module does deserves a better documentation ;-)
I put a couple of comments (most of them very subjective and personal, so don't feel personally attacked), in any case, we'll need @hokaccha 's opinion.
Also, feel free to cherry-pick my comments.
| # node-jwt-simple | ||
| <div align="center"> | ||
| <img src="https://jwt.io/assets/logo.svg"><br><br> | ||
| </div> |
There was a problem hiding this comment.
Not a huge fan of using this external resource, we do not want people to think that jwt.io (which is maintained by auth0) endorses this module in any way.
Moreover, this looks like marketing material, and I don't think we need this.
|
|
||
| [JWT(JSON Web Token)](http://self-issued.info/docs/draft-jones-json-web-token.html) encode and decode module for node.js. | ||
| # Welcome | ||
| Secure your application in seconds using standardised **JWT-Tokens**. [RFC 7519](https://tools.ietf.org/html/rfc7519) |
There was a problem hiding this comment.
This awfully looks like marketing as well. I would go for something more neutral, such as:
This module allows you to implement authentication in your web applications using JSON Web Tokens (aka JWT). JWTs are standardized in [RFC 7519](https://tools.ietf.org/html/rfc7519).
|
|
||
| ## Sample Use-Case | ||
| You may use this as an authentication-method for your API: on one route you encode a token, storing the authenticated user (e.g. after checking password and email) in it. On all other routes you check if the token is valid - this indicates that the user once did authenticate himself successfully. | ||
|
|
There was a problem hiding this comment.
Not a huge fan of this kind of introductions, this looks not necessary here, but that is just my opinion.
| $ npm install jwt-simple | ||
|
|
||
| ## Usage | ||
| ### Encoding | ||
| Encode a Object into your token - the `jwt.encode` function takes a maximum of 3 parameters: |
There was a problem hiding this comment.
Since the parameters are almost self-explanatory, here is a proposal:
### jwt.encode(payload, secret, [algorithm])
Creates a token from a payload. The available algorithms are `HS256` (default), `HS384`, `HS512` and `RS256`.
Example:
...
There was a problem hiding this comment.
Using the signature of the method in the title allows the user to get an idea of the API right from the start, even before reading the doc, which is good !
| | token | the token previously generated | No | | ||
| | secret | key which previously encoded the token | No | | ||
| | noVerify | turn off verification **ON YOUR OWN RISK** | Yes | | ||
| | algorithm | select another algorithm. see encode for algorithm options. | Yes, but noVerify must been set before | |
There was a problem hiding this comment.
Same comment as for encode, I'd try for a simpler way of explaining things:
### jwt.decode(token, secret, [noVerify], [algorithm])
...
Also:
- I would go for a slightly less violent warning (after all, OS licenses are mostly "at your own risk"), maybe
**turn off** verification, or explain what it does, - "Yes, but noVerify must been set before" that is the way js works, I don't think you need to tell this to the user.
| * jwt.decode(token, key, noVerify, algorithm) | ||
| */ | ||
| var jwt = require('jwt-simple'); | ||
| var secret = Buffer.from('fe1a1915a379f3be5394b64d14794932', 'hex'); |
There was a problem hiding this comment.
Are you sure that this is a Buffer ? The jsdoc says String...
|
|
||
| [JWT(JSON Web Token)](http://self-issued.info/docs/draft-jones-json-web-token.html) encode and decode module for node.js. | ||
| # Welcome |
|
@jakoblorz Thank you for your good documentation. I totally agree with @alexjab's comments so could you fix them? |
Hi,
I just thought I had to update the readme because the structure was not that easy to follow (it was in no way bad but I think it might be better now). I have no problem if this pull request is declined, as it is more an "offer" 😄 . Greetings, Jakob Lorz