auth

Author: mikejolley

source/includes/wp-api-v1/_authentication.md

@@ -1,10 +1,10 @@
 # Authentication #
 
-WooCommerce includes by default two ways to authenticate with the WP REST API, depending on whether the site supports SSL. It's still possible to use any [WP REST API authetication](http://v2.wp-api.org/guide/authentication/) plugin or method too.
+WooCommerce includes two ways to authenticate with the WP REST API. In addition, it is possible to use any [WP REST API authentication](http://v2.wp-api.org/guide/authentication/) plugin or method too.
 
 ### Over HTTPS ###
 
-You may use [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication) by providing the REST API Consumer Key as the username and the REST API Consumer Secret as the password.
+You may use [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication) by providing the REST API Consumer Key as the username and the REST API Consumer Secret as the password. 
 
 > HTTP Basic Auth example
 
@@ -13,7 +13,7 @@ curl https://www.example.com/wc-api/v3/orders \
     -u consumer_key:consumer_secret
 ```
 
-Occasionally some servers may not parse the Authorization header correctly (if you see a "Consumer key is missing" error when authenticating over SSL, you have a server issue). In this case, you may provide the consumer key/secret as query string parameters.
+Occasionally some servers may not parse the Authorization header correctly (if you see a "Consumer key is missing" error when authenticating over SSL, you have a server issue). In this case, you may provide the consumer key/secret as query string parameters instead.
 
 > Example for servers that not properly parse the Authorization header:
 
@@ -23,46 +23,60 @@ curl https://www.example.com/wc-api/v3/orders?consumer_key=123&consumer_secret=a
 
 ### Over HTTP ###
 
-You must use [OAuth 1.0a "one-legged" authentication](http://tools.ietf.org/html/rfc5849) to ensure REST API credentials cannot be intercepted. Typically you will use any standard OAuth 1.0a library in the language of choice to handle the authentication, or generate the necessary parameters by following the following instructions.
+You must use [OAuth 1.0a "one-legged" authentication](http://tools.ietf.org/html/rfc5849) to ensure REST API credentials cannot be intercepted by an attacker. Typically you will use any standard OAuth 1.0a library in the language of your choice to handle the authentication, or generate the necessary parameters by following the following instructions.
 
 #### Generating an OAuth signature ####
 
-1) Set the HTTP method for the request:
+1) Set the HTTP method for the request to `GET`
 
-`GET`
+2) Set your base request URI -- this is the full request URI without query string parameters and URL encode according to RFC 3986.
 
-2) Set your base request URI -- this is the full request URI without query string parameters -- and URL encode according to RFC 3986:
+> Example before encoding:
 
-`http://www.example.com/wp-json/wc/v1/orders`
+```
+http://www.example.com/wp-json/wc/v1/orders
+```
+
+> After encoding:
+
+```
+http%3A%2F%2Fwww.example.com%2Fwp-json%2Fwc%2Fv1%2Forders
+```
 
-when encoded:
+3) Collect and normalize your query string parameters. This includes all `oauth_*` parameters except for the signature itself. Parameters should be normalized using URL encoding according to RFC 3986 (use `rawurlencode` in PHP) and percent(`%`) characters should be double-encoded (e.g. `%` becomes `%25`.
 
-`http%3A%2F%2Fwww.example.com%2Fwp-json%2Fwc%2Fv1%2Forders`
+4) Sort the parameters in byte-order.
 
-3) Collect and normalize your query string parameters. This includes all `oauth_*` parameters except for the signature. Parameters should be normalized by URL encoding according to RFC 3986 (`rawurlencode` in PHP) and percent(`%`) characters should be double-encoded (e.g. `%` becomes `%25`.
+> PHP sorting example:
 
-4) Sort the parameters in byte-order (`uksort( $params, 'strcmp' )` in PHP)
+```
+uksort( $params, 'strcmp' )
+```
 
-5) Join each parameter with an encoded equals sign (`%3D`):
+5) Join each parameter with an encoded equals sign (`%3D`) and each key/value pair with an encoded ampersand (`%26`)
 
-`oauth_signature_method%3DHMAC-SHA1`
+> Parameters example:
 
-6) Join each parameter key/value with an encoded ampersand (`%26`):
+```
+oauth_consumer_key%3Dabc123%26oauth_signature_method%3DHMAC-SHA1
+```
 
-`oauth_consumer_key%3Dabc123%26oauth_signature_method%3DHMAC-SHA1`
+6) Form the string to sign by joining the HTTP method, encoded base request URI, and encoded parameter string with an unencoded ampersand symbol (&)
 
-7) Form the string to sign by joining the HTTP method, encoded base request URI, and encoded parameter string with an unencoded ampersand symbol (&):
+> Final string:
 
-`GET&http%3A%2F%2Fwww.example.com%2Fwp-json%2Fwc%2Fv1%2Forders&oauth_consumer_key%3Dabc123%26oauth_signature_method%3DHMAC-SHA1`
+```
+GET&http%3A%2F%2Fwww.example.com%2Fwp-json%2Fwc%2Fv1%2Forders&oauth_consumer_key%3Dabc123%26oauth_signature_method%3DHMAC-SHA1
+```
 
-8) Generate the signature using the string to key and your consumer secret key
+7) Generate the signature using the string to key and your consumer secret key
 
 If you are having trouble generating a correct signature, you'll want to review the string you are signing for encoding errors. The [authentication source](https://github.com/woothemes/woocommerce/blob/master/includes/api/class-wc-rest-authentication.php#L141) can also be helpful in understanding how to properly generate the signature.
 
 #### OAuth Tips ####
 
 * The OAuth parameters must be added as query string parameters and *not* included in the Authorization header. This is because there is no reliable cross-platform way to get the raw request headers in WordPress.
-* The require parameters are: `oauth_consumer_key`, `oauth_timestamp`, `oauth_nonce`, `oauth_signature`, and `oauth_signature_method`. `oauth_version` is not required and should be omitted.
+* The required parameters are: `oauth_consumer_key`, `oauth_timestamp`, `oauth_nonce`, `oauth_signature`, and `oauth_signature_method`. `oauth_version` is not required and should be omitted.
 * HMAC-SHA1 or HMAC-SHA256 are the only accepted hash algorithms.
 * The OAuth nonce can be any randomly generated 32 character (recommended) string that is unique to the consumer key. Read more suggestions on [generating nonces on the Twitter REST API forums](https://dev.twitter.com/discussions/12445).
 * The OAuth timestamp should be the unix timestamp at the time of the request. The REST API will deny any requests that include a timestamp outside of a 15 minute window to prevent replay attacks.

source/stylesheets/screen.css.scss

@@ -127,6 +127,7 @@ html, body {
 		color: $nav-active-text;
 		a:hover {
 			text-decoration: none;
+			background-color: $nav-active-bg;
 		}
 	}
 
@@ -329,6 +330,10 @@ html, body {
 		margin-bottom: 20px;
 	}
 
+	h4 {
+		font-weight: bold;
+	}
+
 	// h2s right after h1s should bump right up
 	// against the h1s.
 	h1 + h2, h1 + div + h2 {
@@ -486,7 +491,7 @@ html, body {
 		clear:right;
 		width: $examples-width;
 		padding: 0 20px;
-    white-space: pre-wrap;
+		white-space: normal;
 
 		&>p { margin: 0; }
 
@@ -500,6 +505,7 @@ html, body {
 	pre {
 		@extend %code-font;
 		background: $examples-bg;
+		white-space: pre-wrap;
 
 		code {
 			padding: 20px;