woothemes/woocommerce — pull request #4055 by maxrice (2013-11-04 07:02:18+00:00)
Title: REST API - Initial Implementation

This is the initial version of the REST API. It is still very experimental but ready for feedback and testing. Please do not merge this quite yet, as there's likely to be quite a bit of changes required before it's ready.

This uses some code from the [WP API](https://github.com/WP-API/WP-API) project, mainly the [WP-JSON-Server class](https://github.com/WP-API/WP-API/blob/master/lib/class-wp-json-server.php). It makes routing and other response-related stuff outrageously easy. My only issue is that it couples a JSON response type very tightly to the routing, which makes it impossible for us to support XML-based responses.

I think the routing handling could be refactored into a base class, and two sub-classes created, one to handle JSON and the other to handle XML. This would also make it easier to make the entire class more WooCommerce-specific, which prevents any unexpected conflicts if a user is running the WP-API as a plugin on their server, or if it's merged into WP core. @rmccue - would love your feedback on this :)

Authentication is handled two ways. First, if Force Checkout SSL is enabled, the API index declares support for SSL and API requests can be easily authenticated by passing the consumer key and secret key as HTTP Basic Auth username/password.

If SSL is not available, API requests must be signed according to the [OAuth 1.0a spec](http://tools.ietf.org/html/rfc5849), implemented as ["one-legged" OAuth](http://oauthbible.com/#oauth-10a-one-legged). This means that every request is signed and authenticated instead of the consumer receiving a token for future use. While it's somewhat of a pain to implement, it's the *only* way to ensure requests are secure when using plain HTTP.

## General Questions
* How should order/coupon/product/customer meta be implemented? I like the idea of a `meta` attribute for each of the response objects that can be enabled with something like `?include_meta=true` or similar in the request.
* Should [get_json_url()](https://github.com/maxrice/woocommerce/blob/api-dev/includes/wc-core-functions.php#L349) and [json_url()](https://github.com/maxrice/woocommerce/blob/api-dev/includes/wc-core-functions.php#L365)
* WP 3.7 is required for date filtering, anyone have issues with this?
* Global functions to create orders/products would be very helpful in reducing code duplication. Order/Product clones of [woocommerce_create_new_customer](https://github.com/maxrice/woocommerce/blob/api-dev/includes/wc-customer-functions.php#L42) would be perfect

## Todos

### General
- [ ] Add store-specific information to API index, like currency, base location, etc
- [ ] Permission checks for reading/editing/deleting (via generic `getResource()` call with `current_user_can` checks)
- [ ] Date standardization for requests/responses, see [these methods](https://github.com/maxrice/woocommerce/blob/api-dev/includes/libraries/wp-api/class-wp-json-server.php#L567)
- [ ] filterFields() method should support specifying sub-fields, e.g. billing_address.country
- [ ] Refactor ID checks into base class method
- [ ] Refactor method names to snake_case if refactoring routing class
- [ ] Add Navigational/Total count response headers

### Orders
- `/orders` returns orders with any status by default, should default be processing/completed instead?
* What should be used for line_item_total?
* should totals be cast to string so they're string quoted in json response?

### Products
- When requesting a variation ID, should the response include *only* the variation product? or should it include the variable parent product, and the requested variation listed as the only variation?
- [ ] Implement Get method
- [ ] Implement Edit method
- [ ] Implement Update method

### Customers
- [ ] Support `created_at_min`/`created_at_max` with `pre_user_query filter `using [this](http://wordpress.stackexchange.com/questions/51485/how-can-i-query-all-users-who-registered-today)
- [ ] Implement Create method
- [ ] Implement Edit method
- [ ] DRY valid user checking code

### Coupons
* Should the `/coupons` endpoint have a custom parameter for getting coupons by coupon code? The `q` parameter searches both code/description already

### Reports
- [ ] Implement Get Sales Report method

### Authentication
* API keys are currently 1 per user (and API requests run under the WP permissions of that user), should we support multiple keys per user?
* should API secret keys be hashed prior to storage? This would prevent accessing the plaintext key again after it's displayed + stored
* Needs testing and sample client code in PHP

### Settings
- [ ] Implement key management
- [ ] Implement API request logging

### Documentation
* Creating signatures, see [good OAuth 1.0 reference](https://dev.twitter.com/docs/auth/creating-signature)
* Creating nonces, see [reference](https://dev.twitter.com/discussions/12445)