Permalink
Browse files

Add app_get, app_post, update docs

  • Loading branch information...
1 parent 30041c8 commit c2b1ea119b3741fbc8e544445e042c11a726b280 @kyledrake kyledrake committed May 5, 2012
Showing with 131 additions and 23 deletions.
  1. +26 −16 README.md
  2. +83 −6 lib/geoloqi/session.rb
  3. +1 −1 lib/geoloqi/version.rb
  4. +4 −0 spec/env.rb
  5. +17 −0 spec/geoloqi/session_spec.rb
View
@@ -1,16 +1,13 @@
-Geoloqi Library for Ruby [![](https://secure.travis-ci.org/geoloqi/geoloqi-ruby.png)](http://travis-ci.org/geoloqi/geoloqi-ruby)
-===
+# Geoloqi Library for Ruby [![](https://secure.travis-ci.org/geoloqi/geoloqi-ruby.png)](http://travis-ci.org/geoloqi/geoloqi-ruby)
Powerful, flexible, lightweight interface to the Geoloqi Platform API.
This library was developed with two goals in mind: to be as simple as possible, but also to be very powerful to allow for much higher-end development (multiple Geoloqi apps per instance, concurrency, performance, thread-safety).
-Installation
----
+##Installation
gem install geoloqi
-Basic Usage
----
+##Basic Usage
Geoloqi uses OAuth2 for authentication, but if you're only working with your own account, you don't need to go through the authorization steps. Simply go to your account settings on the [Geoloqi Developers Site](https://developers.geoloqi.com), click on "Get Started" and copy the permanent access token. You can use this token to run the following examples.
If you just need to make simple requests, you can just make a simple get or post request from Geoloqi:
@@ -62,8 +59,7 @@ You can send query string parameters with get requests too:
# or
geoloqi.get 'location/history?count=2'
-Hashie::Mash support
----
+##Hashie::Mash support
Want to access in a more OOP/JSON style way? Use Hashie::Mash as the response object:
require 'hashie'
@@ -74,8 +70,7 @@ Want to access in a more OOP/JSON style way? Use Hashie::Mash as the response ob
response['layer_id'] # this works too
response[:layer_id] # so does this
-Implementing OAuth2
----
+##Implementing OAuth2
We have integrated OAuth2 support into the gem for your convenience, and provided a Geoloqi plugin for Sinatra. This is all it takes to get a "Hello World" for OAuth2 with Geoloqi:
@@ -102,16 +97,31 @@ Visit the [Geoloqi Sinatra plugin](http://github.com/geoloqi/sinatra-geoloqi) pa
A lower-level demonstration of the OAuth2 code can be found in the examples folder. This may be useful for anyone working to embed with other frameworks (such as Ruby on Rails).
-Found a bug?
----
+##Making requests on behalf of the application
+Some actions (such as creating a user account for your application) require escalated privileges. To use these, call app\_get and app\_post:
+
+ geoloqi.app_post 'user/create_anon'
+
+## API Documentation
+The API has been extensively documented at [our developers site](https://developers.geoloqi.com/api).
+
+## RDoc/YARD Documentation
+The code has been fully documented, and the latest version is always available at the [Rubydoc Site](http://rubydoc.info/gems/geoloqi).
+
+## Running the Tests
+
+ $ bundle install
+ $ bundle exec rake
+
+In addition to a full test suite, there is Travis integration for 1.9, JRuby and Rubinius. 1.8 is supported, however Travis tests have been disabled because 1.8's random hashing sometimes breaks Webmock. I highly recommend looking into upgrading to Ruby 1.9.. it's awesomer.
+
+##Found a bug?
Let us know! Send a pull request or a patch. Questions? Ask! We're here to help. File issues, we'll respond to them!
-Authors
----
+##Authors
* Kyle Drake
* Aaron Parecki
-TODO / Possible projects
----
+##TODO / Possible projects
* Rails plugin (works fine as-is, but maybe we can make it easier?)
* More Concrete API in addition to the simple one?
View
@@ -83,6 +83,83 @@ def authorize_url(redirect_uri=@config.redirect_uri, opts={})
Geoloqi.authorize_url @config.client_id, redirect_uri, opts
end
+ # Makes a GET request to the Geoloqi API server with application credentials. The client_id and client_secret are
+ # sent via an HTTP Authorize header, as per the OAuth2 spec. Otherwise, this method is equivelant to #get.
+ #
+ # This is required for API calls which require escalated privileges, such as retreiving user information for a user
+ # that is not associated with your current access token (GET user/list/ANOTHER_USERS_ID).
+ #
+ # If you don't require application privileges, you should use the regular #get method instead.
+ #
+ # See the Authorization section of the Geoloqi Platform API documentation for more information.
+ #
+ # @param [String] path
+ # Path to the resource being requested.
+ #
+ # @param [String, Hash] query (optional)
+ # A query string or Hash to be appended to the request.
+ #
+ # @param [Hash] headers (optional)
+ # Adds and overwrites headers in request sent to server.
+ #
+ # @return [Hash,Hashie::Mash]
+ # @see #app_post
+ # @see #get
+ # @example
+ # # Request user information, for a user not associated with the current user access token.
+ # result = geoloqi_session.app_get 'YOUR ACCESS TOKEN', 'user/list/ANOTHER_USERS_ID'
+ def app_get(path, query=nil, headers={})
+ app_run :get, path, query, headers
+ end
+
+ # Makes a POST request to the Geoloqi API server with application credentials. The client_id and client_secret are
+ # sent via an HTTP Authorize header, as per the OAuth2 spec. Otherwise, this method is equivelant to #post.
+ #
+ # This is required for API calls which require escalated privileges, such as creating a user account (user/create, user/create_anon)
+ # or making a request for an access token (oauth/token).
+ #
+ # If you don't require application privileges, you should use the regular #post method instead.
+ #
+ # See the Authorization section of the Geoloqi Platform API documentation for more information.
+ #
+ # @param [String] path
+ # Path to the resource being requested (example: '/account/profile').
+ #
+ # @param [String, Hash] query (optional)
+ # A query string or Hash to be converted to POST parameters.
+ #
+ # @param [Hash] headers (optional)
+ # Adds and overwrites headers in request sent to server.
+ #
+ # @return [Hash,Hashie::Mash]
+ # @see #app_get
+ # @see #post
+ # @example
+ # # Create a new layer
+ # result = geoloqi_session.post 'layer/create', :name => 'Portland Food Carts'
+ def app_post(path, query=nil, headers={})
+ app_run :post, path, query, headers
+ end
+
+ # Makes a request to the Geoloqi API server with escalated privileges.
+ #
+ # @return [Hash,Hashie::Mash]
+ # @see #app_get
+ # @see #app_post
+ # @example
+ # # Create a new layer
+ # result = geoloqi_session.run :get, 'layer/create', :name => 'Northeast Portland'
+ def app_run(meth, path, query=nil, headers={})
+ raise Error, 'client_id and client_secret are required to make application requests' unless @config.client_id? && @config.client_secret?
+
+ credentials = "#{@config.client_id}:#{@config.client_secret}"
+
+ # Base64.strict_encode64 in 1.9, but we're using pack directly for compatibility with 1.8.
+ headers['Authorization'] = "Basic " + [credentials].pack("m0")
+
+ run meth, path, query, headers
+ end
+
# Makes a GET request to the Geoloqi API server and returns response.
#
# @param [String] path
@@ -95,13 +172,14 @@ def authorize_url(redirect_uri=@config.redirect_uri, opts={})
# Adds and overwrites headers in request sent to server.
#
# @return [Hash,Hashie::Mash]
+ # @see #app_get
# @see #post
# @example
# # Get your user profile
- # result = geoloqi_session.get 'YOUR ACCESS TOKEN', 'account/profile'
+ # result = geoloqi_session.get 'account/profile'
#
# # Get the last 5 locations
- # result = geoloqi_session.get 'YOUR ACCESS TOKEN', 'account/profile', :count => 5
+ # result = geoloqi_session.get 'account/profile', :count => 5
def get(path, query=nil, headers={})
run :get, path, query, headers
end
@@ -119,6 +197,7 @@ def get(path, query=nil, headers={})
#
# @return [Hash,Hashie::Mash]
# @see #get
+ # @see #app_post
# @example
# # Create a new layer
# result = geoloqi_session.post 'layer/create', :name => 'Portland Food Carts'
@@ -216,13 +295,11 @@ def batch(&block)
# @see #application_access_token
def establish(opts={})
raise Error, 'client_id and client_secret are required to get access token' unless @config.client_id? && @config.client_secret?
- auth = post 'oauth/token', {:client_id => @config.client_id,
+ auth = post 'oauth/token', {:client_id => @config.client_id,
:client_secret => @config.client_secret}.merge!(opts)
- # expires_at is likely incorrect. I'm chopping 5 seconds
- # off to allow for a more graceful failover.
- auth['expires_at'] = auth_expires_at auth['expires_in']
self.auth = auth
+ self.auth[:expires_at] = auth_expires_at auth[:expires_in]
self.auth
end
View
@@ -3,6 +3,6 @@ module Geoloqi
#
# @return [String]
def self.version
- '0.9.40'
+ '0.9.41'
end
end
View
@@ -20,4 +20,8 @@ def auth_headers(access_token='access_token1234')
def api_url(path); "#{Geoloqi.api_url}/#{Geoloqi.api_version}/#{path}" end
+def api_url_with_auth(path)
+ Addressable::URI.parse(api_url(path)).merge(:user => CLIENT_ID, :password => CLIENT_SECRET).to_s
+end
+
include WebMock::API
@@ -261,6 +261,23 @@ class NotFoundError < ApiError; end
@session = Geoloqi::Session.new :config => {:client_id => CLIENT_ID, :client_secret => CLIENT_SECRET}
end
+ it 'should automatically provide client_id and client_secret for app resource calls' do
+ stub_request(:get, api_url_with_auth('user/list/notme')).
+ to_return(:status => 200,
+ :body => {:username => 'captainpicard'}.to_json)
+
+ resp = @session.app_get 'user/list/notme'
+ resp[:username].must_equal 'captainpicard'
+
+ stub_request(:post, api_url_with_auth('user/create_anon')).
+ with(:body => {:device_id => 'abcd'}.to_json).
+ to_return(:status => 200,
+ :body => {:username => 'captainpicard'}.to_json)
+
+ resp = @session.app_post 'user/create_anon', {:device_id => 'abcd'}
+ resp[:username].must_equal 'captainpicard'
+ end
+
it 'retreives application access token data' do
stub_request(:post, api_url('oauth/token')).
with(:body => {:client_id => CLIENT_ID,

0 comments on commit c2b1ea1

Please sign in to comment.