# GunBroker GunBroker.com API Ruby library. ## Installation Add this line to your application's Gemfile: ```ruby gem 'gun_broker' ``` And then execute: $ bundle Or install it yourself as: $ gem install gun_broker ## Usage ### Developer Token You **must** set a developer key obtained from GunBroker.com in order to use this library. ```ruby GunBroker.dev_key = 'your-sekret-dev-key' ``` ### GunBroker::User Authentication requires a `username` and an 'auth options' hash that requires **at least** a `password` *or* `token`. If a password is given, you must call `User#authenticate!` to obtain an access token. ```ruby # By username/password: user = GunBroker::User.new('username', password: 'sekret-password') user.authenticate! user.token # => 'user-access-token' # Or with an existing Access Token: user = GunBroker::User.new('username', token: 'user-access-token') # No need to call #authenticate! since we already have an access token. user.token # => 'user-access-token' ``` Once the User has an access token, you can then grab all of their items (listings). All items methods return an array of `GunBroker::Item` instances. ```ruby user.items # => [GunBroker::Item, ...] user.items_unsold # => [GunBroker::Item, ...] user.items_sold # => [GunBroker::Item, ...] ``` To revoke the access token, call `User#deauthenticate!`. This method is also aliased as `#revoke_access_token!`. ```ruby user.token # => 'user-access-token' user.deauthenticate! user.token # => nil ``` ### GunBroker::Item Represents an item (listing) on GunBroker. The `Item#id` method returns the value of the `itemID` attribute from the response. All other attributes can be accessed through the `Item#[]` method. ```ruby item.id # => '1234567' item['title'] # => 'Super Awesome Scope' ``` ### GunBroker::Category Returns GunBroker category responses. To get an array of all categories, call `Category#all()`. ```ruby GunBroker::Category.all # => [GunBroker::Category, ...] ``` You can also pass an optional parent category ID, to only return subcategories of the given parent. For example, if the 'Firearms' category has an ID of '123', get all Firearm subcategories like this: ```ruby firearms = '123' # ID of the Firearms Category GunBroker::Category.all(firearms) # => [GunBroker::Category, ...] ``` Much like GunBroker::Item, the `Category#id` method returns the `categoryID` attribute from the response. All other attributes can be accessed with `Category#[]`. ```ruby category.id # => '123' category['categoryName'] # => 'Firearms' ``` ### GunBroker::API If you need to access an API endpoint not yet supported, you can use `GunBroker::API` directly. Currently supported HTTP methods are `GET`, `DELETE`, and `POST`, with each having a corresponding method on the `GunBroker::API` class. Each method requires a `path` and accepts optional `params` and `headers` hashes. If making a `GET` request, the `params` will be URL params; if making a `POST` request, the `params` will be turned into JSON and set as the request body. You can also set HTTP headers by passing a hash as the third argument. Headers will **always** contain: * `Content-Type: application/json` * `X-DevKey: your-sekret-dev-key` The response will be parsed JSON (hash). ```ruby GunBroker::API.get('/some/resource') # => { 'name' => 'resource', 'foo' => 'bar' } GunBroker::API.post('/some/resource', { name: 'some data' }) # No params, but some headers: GunBroker::API.delete('/some/resource', {}, { 'X-TestHeader' => 'FooBar' }) ``` ### Error Handling Methods that require authorization (with an access token) will raise a `GunBroker::Error::NotAuthorized` exception if the token isn't valid. Otherwise, if there is some other issue with the request (namely, the response status code is not in the `2xx` range), a `GunBroker::Error::RequestError` will be raised. ## Contributing 1. Fork it ( https://github.com/ammoready/gun_broker/fork ) 2. Create your feature branch (`git checkout -b my-new-feature`) 3. Commit your changes (`git commit -am 'Add some feature'`) 4. Push to the branch (`git push origin my-new-feature`) 5. Create a new Pull Request