my_john_deere_api 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a67f1e1e70572ea6e1d35d166ce1767c80452860aa7942edee243cbe86b5866
-  data.tar.gz: f0f3bb2a58b767b4e4222b94faf4874851c23298e273ece600f4eee3cfbf016e
+  metadata.gz: 583082ed84766dc6aa88a345861e3a3bb500e3c942ca3d97f68d1c820d518750
+  data.tar.gz: 57ebca5ef53a34f12bca706bc1c944694aa9a6e091a4b65ab00fa436d482d94d
 SHA512:
-  metadata.gz: a65a97d65f76340661f79e644b547ef48a9b14932bc05a37ed4855bc1597bcbc8d7a2aa39b8fc18ff2ef8b8a111db09e4f6f2333f7901a59862ef55ba4bf9e6d
-  data.tar.gz: 7140cb61dda21891a93ed43320d9aa4f425c592be8bf1a84eb27a09665eb4c5a626a547240b34271165b01793c6013cf320bdfecbf42235425d283766671e7b6
+  metadata.gz: a69454221d4dfbf666da2020dd9421049cb782bf62952eb8b13dab9cd2d24c8c7165c396d2e26bfcb5900e3bf56e167f29baa6b0066829a0e44fd0a0eee64247
+  data.tar.gz: d005e5e18b4b59a09c4dfa49791bfff12028f0e209f3ab90b64dae51c738a6d83b02d6ba2a811ebe806ecb046dcd38cfd66b72b69702c268cfe4a440ca83980b

data/README.md

@@ -2,8 +2,10 @@
 
 [![CircleCI](https://circleci.com/gh/Intellifarm/my_john_deere_api.svg?style=svg)](https://circleci.com/gh/Intellifarm/my_john_deere_api)
 
-This client allows you to connect the MyJohnDeere API without having to code your own oauth process, API requests, and pagination.
+This client allows you to connect the [MyJohnDeere API](https://developer.deere.com/#!documentation)
+without having to code your own oauth process, API requests, and pagination.
 
+* Works with Rails, but does not require it
 * Supports both sandbox and live mode
 * 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.
@@ -114,6 +116,141 @@ client = JD::Client.new(
 )
 ```
 
+
+### Using the Client to Do Stuff
+
+Once you're connected, the client works like a simplified version of ActiveRecord. JSON hashes from the API are
+converted into objects to be easier to work with. Collections of things, like organizations, handle pagination
+for you. Just iterate using `each`, `map`, etc, and new pages are fetched as needed.
+
+#### [Organizations](https://developer.deere.com/#!documentation&doc=myjohndeere%2Forganizations.htm)
+
+Organization collections act like a list. In addition to all the methods included via Ruby's
+[Enumerable Module](https://ruby-doc.org/core-2.7.0/Enumerable.html), organization collections support:
+
+* all
+* count
+* first
+* find
+
+The `count` method only requires loading the first page of results, so it's a relatively cheap call. On the other hand,
+`all` forces the entire collection to be loaded from John Deere's API, so use with caution. Organizations cannot be
+created via the API, so there is no `create` method on this collection.
+
+```ruby
+client.organizations
+# => collection of organizations under this client
+
+client.organizations.count
+# => 15
+
+client.organizations.first
+# => a single organization object
+
+organization = client.organizations.find(1234)
+# => a specific organization object, fetched by ID
+
+organization.name
+# => 'Smith Farms'
+
+organization.type
+# => 'customer'
+
+organization.member
+# => true
+
+organization.links
+# =>  {
+#       'self' => 'https://sandboxapi.deere.com/platform/organizations/1234',
+#       'machines' => 'https://sandboxapi.deere.com/platform/organizations/1234/machines',
+#       'wdtCapableMachines' => 'ttps://sandboxapi.deere.com/platform/organizations/1234/machines?capability=wdt'   
+#     }
+
+```
+
+This is much nicer than working with the raw API response:
+
+```json
+{
+   "links": [
+      {
+         "rel": "self",
+         "uri": "https://sandboxapi.deere.com/platform/organizations/1234"
+      },
+      {
+         "rel": "machines",
+         "uri": "https://sandboxapi.deere.com/platform/organizations/1234/machines"
+      },
+      {
+         "rel": "wdtCapableMachines",
+         "uri": "https://sandboxapi.deere.com/platform/organizations/1234/machines?capability=wdt"
+      }
+   ],
+   "id": "1234",
+   "name": "Smith Farms",
+   "type": "customer",
+   "partnerships": [],
+   "member": true
+}
+```
+
+But the real power comes from daisy-chaining associations together.
+
+
+### [Assets](https://developer.deere.com/#!documentation&doc=.%2Fmyjohndeere%2Fassets.htm)
+
+Handles an organization's assets. Supported methods:
+
+* all
+* count
+* first
+* find
+* create
+
+```ruby
+organization = client.organizations.first
+# => the first organization returned by the client
+
+organization.assets
+# => collection of assets
+
+asset = organization.assets.find(123)
+# => asset object, fetched by ID
+
+asset.title
+# => 'AgThing Water Device'
+
+asset.category
+# => 'DEVICE'
+
+asset.type
+# => 'SENSOR'
+
+asset.sub_type
+# => 'OTHER'
+
+asset.links
+# => a hash of API urls related to this asset
+```
+
+Creating an asset requires a contribution\_definition\_id, in addition to the attributes listed in the
+[John Deere API docs](https://developer.deere.com/#!documentation). This method creates the asset in
+the John Deere platform, and returns the newly created record.
+
+```ruby
+asset = organization.assets.create(
+  contribution_definition_id: ENV['CONTRIBUTION_DEFINITION_ID'],
+  title: 'Asset Title',
+  asset_category: 'DEVICE',
+  asset_type: 'SENSOR',
+  asset_sub_type: 'ENVIRONMENTAL'
+)
+
+asset.title
+# => 'Asset Title'
+```
+
+
 ### Direct API Requests
 
 While the goal of the client is to eliminate the need to make/interpret calls to the John Deere API, it's important

data/lib/my_john_deere_api/version.rb

@@ -1,3 +1,3 @@
 module MyJohnDeereApi
-  VERSION='1.0.0'
+  VERSION='1.0.1'
 end

data/test/support/vcr_setup.rb

@@ -141,14 +141,7 @@ class VcrSetup
       title: 'Asset Title',
       asset_category: 'DEVICE',
       asset_type: 'SENSOR',
-      asset_sub_type: 'ENVIRONMENTAL',
-      links: [
-        {
-          '@type' => 'Link',
-          'rel' => 'contributionDefinition',
-          'uri' => "#{url}/contributionDefinitions/#{ENV['CONTRIBUTION_DEFINITION_ID']}"
-        }
-      ]
+      asset_sub_type: 'ENVIRONMENTAL'
     }.freeze
   end
 

metadata

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