Stackd Ruby Client
Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file lib/stackd
. To experiment with that code, run bin/console
for an interactive prompt.
TODO: Delete this and the text above, and describe your gem
Installation
Add this line to your application's Gemfile:
gem 'stackd'
And then execute:
$ bundle
Or install it yourself as:
$ gem install stackd
Usage
Creating a client
$stackd = Stackd::Client.new id: 'YOUR_CLIENT_ID',
secret: 'YOUR_CLIENT_SECRET'
Getting an app token
app_token = $stackd.auth_requests.client scope: 'a,b,c'
# => <Stackd::Token app_id: "YOUR_CLIENT_ID",
# scope: "a,b,c",
# access_token: "e1979b29529ac",
# expires_in: 3600>
Getting a user token
class MyController
def
auth_request = $stackd.auth_requests.new redirect_uri: 'YOUR_CALLBACK_URL',
scope: 'a,b,c'
session[:auth_state] = auth_request.state
redirect_to auth_request.url
# stackd.com/authorize?client_id=...&state=...&redirect_uri=...&scope=...
end
def callback
auth_request = $stackd.auth_requests.new state: session[:state]
user_token = auth_request.callback code: params[:code],
state: params[:state]
# => <Stackd::Token user_id: "09545bce-3c31-4593-99bd-1dfe8b98df93",
# scope: "a,b",
# access_token: "e1979b29529ac",
# refresh_token: "ca92592b9791e",
# expires_in: 3600>
end
end
Refreshing a user token
refreshed_user_token = $stackd.auth_requests.refresh user_token
Persisting tokens (example)
rails generate model TokenData \
user_id:string \
scope:string \
access_token:string \
refresh_token:string \
expires_in:integer
Stackd::Token.on_grant do |token|
TokenData.create! user_id: token.user_id,
scope: token.scope,
access_token: token.access_token,
refresh_token: token.refresh_token,
expires_in: token.expires_in
end
class TokenData
def self.fresh_token_by criteria
# ...
token = $stackd.tokens.new user_id: user_id,
scope: scope,
access_token: access_token,
refresh_token: refresh_token,
expires_in: expires_in,
token_type: 'bearer'
if expired?
$stackd.auth_requests.refresh token
else
token
end
end
def expired?
Time.now > created_at + expires_in.seconds
end
end
Making requests
token.post :rappers, name: 'Marshall Mathers'
# POST /rappers
# {"name": "Marshall Mathers"}
# => { ... }
token.patch :rappers, ':id', name: 'EMIN3M'
# PATCH /rappers/:id
# {"name": "EMIN3M"}
# => { ... }
token.get :rapper, ':id'
# GET /rappers/:id
# => { ... }
token.get :rappers, q: 'Slim Shady'
# GET /rappers?q=Slim%20Shady
# => { rappers: [ ... ], ... }
token.get '/any/url'
# GET /any/url
Application errors (4xx)
Will throw a Stackd::Error
:
# <Stackd::Error error="error_code"
# error_description="Something went wrong."
# error_uri="https://stackd.com/docs/errors#error_code">
Server errors (5xx)
Will throw a Stackd::ServerError
.
Development
After checking out the repo, run bin/setup
to install dependencies. Then, run bin/console
for an interactive prompt that will allow you to experiment. Run bundle exec stackd
to use the code located in this directory, ignoring other installed copies of this gem.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
to create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Contributing
- Fork it ( https://github.com/stackd/stackd-ruby/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request