From 245cbb05958157168b2c4c78b7ed5075627eec56 Mon Sep 17 00:00:00 2001 From: Rich Ellis Date: Wed, 4 Dec 2019 09:59:53 +0000 Subject: [PATCH] Added example to percent encoding documentation --- README.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index f11720d2..64abe19e 100644 --- a/README.md +++ b/README.md @@ -156,14 +156,20 @@ var Cloudant = require('@cloudant/cloudant'); var cloudant = Cloudant("http://MYUSERNAME:MYPASSWORD@localhost:5984"); ~~~ -**Note**: If you pass credentials in the user information subcomponent of the URL -then they must be [percent encoded](https://tools.ietf.org/html/rfc3986#section-3.2.1). -Specifically the characters `: / ? # [ ] @ %` _MUST_ be precent-encoded, other -characters _MAY_ be percent encoded. +**Note**: It is preferred to pass credentials using the `account`/`username` and +`password` configuration options rather than as part of the URL. However, if you +choose to pass credentials in the user information subcomponent of the URL then +they must be [percent encoded](https://tools.ietf.org/html/rfc3986#section-3.2.1). +Specifically within either the username or passowrd the characters `: / ? # [ ] @ %` +_MUST_ be precent-encoded, other characters _MAY_ be percent encoded. +For example for the username `user123` and password `colon:at@321`: +``` +https://user123:colon%3aat%40321@localhost:5984 +``` Credentials must not be percent encoded when passing them via other configuration options besides `url`. -**Note**: If you pass in a `username`, `password`, and `url` that contains +If you pass in `username` and `password` options and a `url` that contains credentials, the `username` and `password` will supercede the credentials within the `url`. For example, `myusername` and `mypassword` will be used in the code below during authentication: