Updated the Oauth Tips, closes woocommerce#7

Author: claudiosanches

source/includes/v2/_introduction.md

@@ -1,28 +1,28 @@
-# Introduction
+# Introduction #
 
 Introduced in WooCommerce 2.1, the REST API allows store data to be created, read, updated, and deleted using the JSON format.
 
-## Requirements
+## Requirements ##
 
 You must be using WooCommerce 2.1 or newer and the REST API must be enabled under `WooCommerce > Settings`. You must enable pretty permalinks, as default permalinks will not work.
 
 <aside class="notice">
 Many endpoints were improving with new versions of WooCommerce, so we always recommend keeping your WooCommerce updated to work properly with this documentation.
 </aside>
 
-## Schema
+## Schema ##
 
 The API is accessible via this endpoint:
 
 `https://www.your-store.com/wc-api/v2`
 
 You may access the API over either HTTP or HTTPS. HTTPS is recommended where possible, as authentication is simpler. The API index will declare if the site supports SSL or not.
 
-## Version
+## Version ##
 
 The current API version is `v2` which takes a first-order position in endpoints. The `v1` endpoint is available in WooCommerce 2.1 / 2.2 / 2.3, but it will be removed in a future version.
 
-### Differences between v1 and v2 versions
+### Differences between v1 and v2 versions ###
 
 * v1 supports XML response format, v2 only supports JSON.
 * v1 does not support creating or updating (with the exception of order status) any resources, v2 supports full create/read/update/delete for all endpoints.
@@ -33,7 +33,7 @@ The current API version is `v2` which takes a first-order position in endpoints.
 * v1 does not include any endpoints for getting valid order statuses, v2 includes an endpoint for listing valid order statuses (`GET /orders/statuses`).
 * v2 supports the core features added in WooCommerce 2.2, primarily order refunds (via the `/orders/refunds` endpoint) and Webhooks (via the `/webhooks`).
 
-## Requests/Responses
+## Requests/Responses ##
 
 The default response format is JSON. Requests with a message-body use plain JSON to set or update resource attributes. Successful requests will return a `200 OK` HTTP status.
 
@@ -49,11 +49,11 @@ Some general information about responses:
 
 * Blank fields are generally included as `null` instead of being blank strings or omitted.
 
-## Authentication
+## Authentication ##
 
 There are two aways to authenticate with the API, depending on whether the site supports SSL or not.  Remember that the Index endpoint will indicate if the site supports SSL or not.
 
-### Over HTTPS
+### Over HTTPS ###
 
 You may use [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication) by providing the API Consumer Key as the username and the API Consumer Secret as the password.
 
@@ -72,10 +72,11 @@ Occasionally some servers may not properly parse the Authorization header (if yo
 curl https://www.example.com/wc-api/v2/orders?consumer_key=123&consumer_secret=abc
 ```
 
-### Over HTTP
+### Over HTTP ###
+
 You must use [OAuth 1.0a "one-legged" authentication](http://tools.ietf.org/html/rfc5849) to ensure API credentials cannot be intercepted. Typically you may use any standard OAuth 1.0a library in your language of choice to handle the authentication, or generate the necessary parameters by following these instructions.
 
-#### Generating an OAuth signature
+#### Generating an OAuth signature ####
 
 1) Set the HTTP method for the request:
 
@@ -109,33 +110,25 @@ when encoded:
 
 If you are having trouble generating a correct signature, you'll want to review your string to sign for errors with encoding. The [authentication source](https://github.com/woothemes/woocommerce/blob/master/includes/api/class-wc-api-authentication.php#L177) can also be helpful in understanding how to properly generate the signature.
 
-#### OAuth Tips
+#### 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 must 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 a nonce](https://dev.twitter.com/discussions/12445) on the Twitter API forums.
-
 * The OAuth timestamp should be the unix timestamp at the time of the request. The API will deny any requests that include a timestamp that is outside of a 15 minute window to prevent replay attacks.
-
 * You must use the store URL provided by the index when forming the base string used for the signature, as this is what the server will use. (e.g. if the store URL includes a `www` sub-domain, you should use it for requests)
-
 * Some OAuth libraries add an ampersand to the provided secret key before generating the signature. This does not adhere to the OAuth spec and the ampersand should be removed prior to generating the signature.
-
 * You may test your generated signature using LinkedIn's [OAuth test console](http://developer.linkedinlabs.com/oauth-test/) -- leave the member token/secret blank.
-
 * Twitter has great instructions on [generating a signature](https://dev.twitter.com/docs/auth/creating-signature) with OAuth 1.0a, but remember tokens are not used with this implementation.
-
 * Note that the request body is *not* signed as per the OAuth spec, see [Google's OAuth 1.0 extension](https://oauth.googlecode.com/svn/spec/ext/body_hash/1.0/oauth-bodyhash.html) for details on why.
+* If including filter fields in your request, it saves a lot of trouble if you can order your filter fields alphabetically before submitting. Many Oauth libraries won't order subquery fields properly, resulting in invalid signatures.
 
-## Parameters
+## Parameters ##
 
 All endpoints accept optional parameters which can be passed as an HTTP query string parameter, e.g. `GET /orders?status=completed`. There are common parameters and endpoint-specific parameters which are documented along with that endpoint.
 
-### Filter Parameter
+### Filter Parameter ###
 
 All endpoints accept a `filter` parameter that scopes individual filters using brackets, like date filtering:
 
@@ -147,7 +140,7 @@ Multiple `filter` parameters can be included and intermixed with other parameter
 
 Note that the following filters are supported for all endpoints except the `reports` endpoint, which has it's own set of filters that are documented along with that endpoint.
 
-#### Available Filters
+#### Available Filters ####
 
 |       Filter       |                                                                                                                                         Description                                                                                                                                          |
 |--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -165,7 +158,7 @@ Note that the following filters are supported for all endpoints except the `repo
 
 Note that Dates should be provided in [RFC3339](http://www.ietf.org/rfc/rfc3339.txt) format in UTC timezone: `YYYY-MM-DDTHH:MM:SSZ`. You may omit the time and timezone if desired.
 
-### Fields Parameter
+### Fields Parameter ###
 
 You may limit the fields returned in the response using the `fields` parameter:
 
@@ -183,7 +176,7 @@ Sub-fields can't be limited for resources that have multiple structs, like an or
 
 `GET /orders?fields=line_items.product_id`
 
-## Pagination
+## Pagination ##
 
 Requests that return multiple items will be paginated to 10 items by default. This default can be changed by the site administrator by changing the `posts_per_page` option. Alternatively the items per page can be specifed with the `?filter[limit]` parameter:
 
@@ -201,7 +194,7 @@ Page number is 1-based and ommiting the `?page` parameter will return the first
 
 The total number of resources and pages are always included in the `X-WC-Total` and `X-WC-TotalPages` HTTP headers.
 
-## Link Header
+## Link Header ##
 
 Pagination info is included in the [Link Header](http://tools.ietf.org/html/rfc5988). It's recommended that you follow these values instead of building your own URLs where possible.
 
@@ -221,7 +214,7 @@ The possible `rel` values are:
 | `first` | Shows the URL of the first page of results              |
 | `prev`  | Shows the URL of the immediate previous page of results |
 
-## Errors
+## Errors ##
 
 Occasionally you might encounter errors when accessing the API. There are four possible types:
 
@@ -284,7 +277,7 @@ Occasionally you might encounter errors when accessing the API. There are four p
 
 Errors return both an appropriate HTTP status code and response object which contains a `code` and `message` attribute. If an endpoint has any custom errors, they are documented with that endpoint.
 
-## HTTP Verbs
+## HTTP Verbs ##
 
 The API uses the appropriate HTTP verb for each action:
 
@@ -296,7 +289,7 @@ The API uses the appropriate HTTP verb for each action:
 | `POST`   | Used for creating resources                                             |
 | `DELETE` | Used for deleting resources                                             |
 
-## JSONP Support
+## JSONP Support ##
 
 The API supports JSONP by default. JSONP responses uses the `application/javascript` content-type. You can specify the callback using the `?_jsonp` parameter for `GET` requests to have the response wrapped in a JSON function:
 
@@ -345,7 +338,7 @@ curl https://example.com/wc-api/v2/orders/count?_jsonp=ordersCount \
 }
 ```
 
-## Webhooks
+## Webhooks ##
 
 Webhooks are an experimental feature in the v2 REST API. They must be managed using the REST API endpoints as a UI is not yet available. The `WC_Webhook` class manages all data storage/retrieval from the custom post type, as well as enqueuing a webhook's actions and processing/delivering/logging the webhook. On `woocommerce_init`, active webhooks are loaded and their associated hooks are added.
 
@@ -357,7 +350,7 @@ Each webhook has:
 * secret: an optional secret key that is used to generate a HMAC-SHA256 hash of the request body so the receiver can verify authenticity of the webhook
 * hooks: an array of hook names that are added and bound to the webhook for processing
 
-### Topics
+### Topics ###
 
 The topic is a combination resource (e.g. order) and event (e.g. created) and maps to one or more hook names (e.g. `woocommerce_checkout_order_processed`). Webhooks can be created using the topic name and the appropriate hooks are automatically added.
 
@@ -370,7 +363,7 @@ Core topics are:
 
 Custom topics can also be used which map to a single hook name, so for example you could add a webhook with topic `action.woocommerce_add_to_cart` that is triggered on that event. Custom topics pass the first hook argument to the payload, so in this example the `cart_item_key` would be included in the payload.
 
-### Delivery/Payload
+### Delivery/Payload ###
 
 Delivery is done using `wp_remote_post()` (HTTP POST) and processed in the background by default using wp-cron. A few custom headers are added to the request to help the receiver process the webhook:
 
@@ -383,7 +376,7 @@ Delivery is done using `wp_remote_post()` (HTTP POST) and processed in the backg
 
 The payload is JSON encoded and for API resources (coupons,customers,orders,products), the response is exactly the same as if requested via the REST API.
 
-### Logging
+### Logging ###
 
 Requests/responses are logged as comments on the webhook custom post type. Each delivery log includes:
 
@@ -397,15 +390,15 @@ After 5 consecutive failed deliveries (as defined by a non HTTP 2xx response cod
 
 Delivery logs can be fetched through the REST API endpoint or in code using `WC_Webhook::get_delivery_logs()`
 
-### Endpoints
+### Endpoints ###
 
 See the webhook resource section.
 
-## Troubleshooting
+## Troubleshooting ##
 
 * Nginx - Older configurations of Nginx can cause issues with the API, see [this issue](https://github.com/woothemes/woocommerce/issues/5616#issuecomment-47338737) for details
 
-## Tools
+## Tools ##
 
 * [WooCommerce REST API Client Library](https://github.com/kloon/WooCommerce-REST-API-Client-Library) - A simple PHP client library by Gerhard Potgieter.
 * [WooCommerce API Client](https://github.com/mac2000/woo-commerce-api-client) - Guzzle wrapper around WooCommerce v2 API plus missign api helpers.