my_john_deere_api 0.12.2 → 0.12.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 19b47734d5e6b4ad385e8ab7a23f2335da7a55cd615e9b893e7a01d32594cedf
-  data.tar.gz: 409d9106defce29a80ef99b98bb958cada379df66c4e01a1c81d44d47b2e96fc
+  metadata.gz: e3237e5669c2065e7cad92bef10e67a23a92ff1c8ae77dc9d8108034d1e903d5
+  data.tar.gz: 94a533836b5a55c9626640b3bfce071e34b579c9ae3ad9794cab85cf93c6db93
 SHA512:
-  metadata.gz: 8d0133e30516d2a70e9fbd466ed74b2a6aefc8dbcbf69cd84cf935742e682d4077571db4839bcfd49ee2a707f901bfa87012b3c49e07f5d3176a36f7277de490
-  data.tar.gz: e3e87c29522b6e70fca48b612ac13a19d78abcfc9c27f2f755f8a601630f336092dc325f932b98db7985755f931a6d1041fb9df6a437e58c6aba6c0bb7c67183
+  metadata.gz: cd988f0992634f6b0ed2f22cf68c055e73c78ba1a9f0cbfaeb42f9ad81d8394dccb3271b0ad006951d04236645a3c8b57cec67f72215252e56556f0514eeb277
+  data.tar.gz: 7f5d2d31cb5f13c3cfbbfb5d075ed12e6c634d68b95a82fbba8885bf56fef273ee9e16b239f69bf5a63d20bc2f611df9c68bb9027b42c119136579833b947948

data/README.md

@@ -8,4 +8,79 @@ This client allows you to connect the MyJohnDeere API without having to code you
 * Simplifies the oAuth negotiation process
 * Uses ruby enumerables to handle pagination behind the scenes. Calls like `each`, `map`, etc will fetch new pages of data as needed.
 
+## Documentation
+
+We provide RDoc documentation, but here is a helpful guide for getting started. Because the gem name is long, all examples are going
+to assume this shortcut:
+
+    JD = MyJohnDeereApi
+
+So that when you see:
+
+    JD::Authorize
+
+It really means:
+
+    MyJohnDeereApi::Authorize
+
+
+### Authorizing with John Deere via Auth 1.0
+
+This is the simplest path to authorization, though your user has to jump through an extra hoop of giving you the verification code:
+  
+    # Create an authorize object, using your app's API key and secret. You can
+    # pass an environment (`:live` or `:sandbox`), which default to `:live`.
+    authorize = JD::Authorize.new(API_KEY, API_SECRET, environment: :sandbox)
+    
+    # Retrieve a valid authorization url from John Deere, where you can send 
+    # your user for authorizing your app to the JD platform.
+    url = authorize.authorize_url
+    
+    # Verify the code given to the user during the authorization process, and
+    # turn this into access credentials for your user.
+    authorize.verify(code)    
+
+In reality, you will likely need to re-instantiate the authorize object when the user returns, and that works without issue:
+
+    # Create an authorize object, using your app's API key and secret.
+    authorize = JD::Authorize.new(API_KEY, API_SECRET, environment: :sandbox)
+    
+    # Retrieve a valid authorization url from John Deere.
+    url = authorize.authorize_url
+    
+    # Queue elevator music while your app serves other users...
+    
+    # Re-create the authorize instance in a different process
+    authorize = JD::Authorize.new(API_KEY, API_SECRET, environment: :sandbox)
+    
+    # Proceed as normal
+    authorize.verify(code)
+
+In a web app, you're prefer that your user doesn't have to copy/paste verification codes. So you can pass in an :oauth_callback url.
+When the user authorizes your app with John Deere, they are redirected to the url you provide, with the paraameter 'oauth_verifier'
+that contains the verification code so the user doesn't have to provide it.
+
+    # Create an authorize object, using your app's API key and secret.
+    authorize = JD::Authorize.new(
+      API_KEY, 
+      API_SECRET, 
+      environment: :sandbox,
+      oauth_callback: 'https://example.com'
+    )
+    
+    # Retrieve a valid authorization url from John Deere.
+    # This will contain the callback url encoded into the
+    # query string for you.
+    url = authorize.authorize_url
+    
+    # Queue elevator music while your app serves other users...
+    
+    # Re-create the authorize instance in a different process.
+    # It's not necessary to re-initialize with the callback url.
+    authorize = JD::Authorize.new(API_KEY, API_SECRET, environment: :sandbox)
+    
+    # Inside a Rails controller, you might do this:
+    authorize.verify(params[:oauth_verifier])
+
+
 More details coming soon.

data/lib/my_john_deere_api/authorize.rb

@@ -26,7 +26,7 @@ module MyJohnDeereApi
     end
 
     ##
-    # Option a url which may be used to obtain a verification
+    # Url which may be used to obtain a verification
     # code from the oauth server.
 
     def authorize_url

data/lib/my_john_deere_api/version.rb

@@ -1,3 +1,3 @@
 module MyJohnDeereApi
-  VERSION='0.12.2'
+  VERSION='0.12.3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: my_john_deere_api
 version: !ruby/object:Gem::Version
-  version: 0.12.2
+  version: 0.12.3
 platform: ruby
 authors:
 - Jaime Bellmyer