README.markdown in ruby-mws-0.0.3 vs README.markdown in ruby-mws-0.0.4
- old
+ new
@@ -1,43 +1,50 @@
ruby-mws
========
-Under development
------------------
+by Erik Lyngved
-This is a Ruby gem that wraps the Amazon Marketplace Web Service (MWS) API. It is still missing many features, but some basic requests are available.
+### Read me!
-Please use at your own risk. This has not been tested thoroughly and is not guaranteed to work in any capacity. See the LICENSE file for more details.
+ruby-mws is a Ruby gem that wraps the Amazon Marketplace Web Service (MWS) API. Right now it only supports Amazon's Order and Inventory APIs.
+I made this gem for my own purposes, and it's not fully featured. Pull requests or bug reports are always welcome.
+
Quick Start
-----------
-### Initialize the connection object
+To quickly test your connection to the service without credentials, you can ping the server, which returns server time in UTC:
+ MWS::Base.server_time
+
+### Initialization
+
Pass in your developer account credentials. All four params below are required.
- mws = MWS.new {:aws_access_key_id => "AKIAIFKEXAMPLE4WZHHA",
+ mws = MWS.new (:aws_access_key_id => "AKIAIFKEXAMPLE4WZHHA",
:secret_access_key => "abc123def456/SECRET/+ghi789jkl",
:seller_id => "A27WEXAMPLEBXY",
- :marketplace_id => "ATVPDKIKX0DER"}
+ :marketplace_id => "ATVPDKIKX0DER")
-### Make a request
+### Requests
-Let's use the Orders API to retrieve recently updated orders.
+We'll use the Orders API to retrieve recently updated orders.
# Retrieve all orders updated within the last 4 hours
- response = mws.orders.list_orders :last_updated_after => Time.now-4.hours # Rails helper used
+ response = mws.orders.list_orders :last_updated_after => 4.hours.ago # ActiveSupport time helper
(All datetime fields accept Time or DateTime objects, as well as strings in iso8601 format.)
-### Parse the response
+### Responses
-We can parse our response to view the orders and any other data returned.
+Response objects inherit [Hashie](http://github.com/intridea/hashie) for easy access and [Rash](http://github.com/tcocca/rash) to convert Amazon's CamelCase convention to underscore. So you're just left with plain ol' Ruby goodness.
+Let's parse our response to view the orders and any other data returned.
+
response.orders.first # => { "amazon_order_id" => "002-EXAMPLE-0031387",
- "purchase_date" => "2012-01-13T19:11:46.000Z",
- ... }
+ # "purchase_date" => "2012-01-13T19:11:46.000Z",
+ # ... }
Response objects are accessible in Hash or method notation.
response.orders == response[:orders] # => true
@@ -48,51 +55,47 @@
### NextToken requests
For responses with long lists of data, results are returned from the service in pages (usually 100 per page). Example:
- response = mws.orders.list_orders :last_updated_after => Time.now-1.week # returns 100 orders
+ response = mws.orders.list_orders :last_updated_after => 1.week.ago # returns 100 orders & next_token
Here, there are more orders to be returned. You can call `has_next?` on the same API instance to see if the last response returned has a next page. If so, calling `next` will make the request for the next page.
mws.orders.has_next? # => true
next_response = mws.orders.next # returns next page of orders
-You can keep calling `next` on the API instance as long as `has_next?` returns true.
+Repeat as necessary. You can keep calling `next` on the API instance as long as `has_next?` returns true.
-You can always go about the manual way as per Amazon's docs:
+Or if you need to, you can save the next_token and go about the manual way as per Amazon's docs:
- next_response = mws.orders.list_orders_by_next_response :next_token => response.next_token
+ next_response = mws.orders.list_orders_by_next_token :next_token => response.next_token
-### Underscore notation
+API
+---
-ruby-mws wraps Amazon's CamelCase convention with Ruby-friendly underscore notation. This goes for request names and params, as well as response field names.
+ @mws = MWS.new(authentication_hash) # initialize the connection object (see above)
-Available Requests
-------------------
-
- @mws = MWS.new(authentication_hash) # initialize the connection object
-
This object can be used to access all API services. Below are examples on how to make the different requests that are available so far. Refer to the [Amazon MWS Reference Docs](https://developer.amazonservices.com/) for available fields for each request.
### Orders API
-* ListOrders - gets orders by time frame and other parameters
+* ListOrders - gets orders by time range and other parameters
- `@mws.orders.list_orders :last_updated_after => Time.now-4.hours`
+ `@mws.orders.list_orders :last_updated_after => Time.now-4.hours, :order_status => 'Shipped'`
* GetOrder - gets orders by Amazon order ID
`@mws.orders.get_order :amazon_order_id => "002-EXAMPLE-0031387"`
`:amazon_order_id` can be an array to retrieve multiple orders.
-* ListOrderItems - gets order items for one order ID
+* ListOrderItems - gets order items for one order ID (only one order at a time here)
`@mws.orders.list_order_items :amazon_order_id => "002-EXAMPLE-0031387"`
### Fulfillment Inventory API
* ListInventorySupply - returns availability of inventory, only returns items based on list of SKUs or last change date
- `@mws.inventory.list_inventory_supply :seller_skus => %w[PF-5VZN-04XR V4-03EY-LAL1 OC-TUKC-031P`
+ `@mws.inventory.list_inventory_supply :seller_skus => ['PF-5VZN-04XR', 'V4-03EY-LAL1', 'OC-TUKC-031P']`
`@mws.inventory.list_inventory_supply :query_start_date_time => Time.now-1.day`
\ No newline at end of file