my_john_deere_api 1.0.0 → 1.0.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +138 -1
- data/lib/my_john_deere_api/version.rb +1 -1
- data/test/support/vcr_setup.rb +1 -8
- metadata +1 -1
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 583082ed84766dc6aa88a345861e3a3bb500e3c942ca3d97f68d1c820d518750
|
4
|
+
data.tar.gz: 57ebca5ef53a34f12bca706bc1c944694aa9a6e091a4b65ab00fa436d482d94d
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: a69454221d4dfbf666da2020dd9421049cb782bf62952eb8b13dab9cd2d24c8c7165c396d2e26bfcb5900e3bf56e167f29baa6b0066829a0e44fd0a0eee64247
|
7
|
+
data.tar.gz: d005e5e18b4b59a09c4dfa49791bfff12028f0e209f3ab90b64dae51c738a6d83b02d6ba2a811ebe806ecb046dcd38cfd66b72b69702c268cfe4a440ca83980b
|
data/README.md
CHANGED
@@ -2,8 +2,10 @@
|
|
2
2
|
|
3
3
|
[![CircleCI](https://circleci.com/gh/Intellifarm/my_john_deere_api.svg?style=svg)](https://circleci.com/gh/Intellifarm/my_john_deere_api)
|
4
4
|
|
5
|
-
This client allows you to connect the MyJohnDeere API
|
5
|
+
This client allows you to connect the [MyJohnDeere API](https://developer.deere.com/#!documentation)
|
6
|
+
without having to code your own oauth process, API requests, and pagination.
|
6
7
|
|
8
|
+
* Works with Rails, but does not require it
|
7
9
|
* Supports both sandbox and live mode
|
8
10
|
* Simplifies the oAuth negotiation process
|
9
11
|
* 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(
|
|
114
116
|
)
|
115
117
|
```
|
116
118
|
|
119
|
+
|
120
|
+
### Using the Client to Do Stuff
|
121
|
+
|
122
|
+
Once you're connected, the client works like a simplified version of ActiveRecord. JSON hashes from the API are
|
123
|
+
converted into objects to be easier to work with. Collections of things, like organizations, handle pagination
|
124
|
+
for you. Just iterate using `each`, `map`, etc, and new pages are fetched as needed.
|
125
|
+
|
126
|
+
#### [Organizations](https://developer.deere.com/#!documentation&doc=myjohndeere%2Forganizations.htm)
|
127
|
+
|
128
|
+
Organization collections act like a list. In addition to all the methods included via Ruby's
|
129
|
+
[Enumerable Module](https://ruby-doc.org/core-2.7.0/Enumerable.html), organization collections support:
|
130
|
+
|
131
|
+
* all
|
132
|
+
* count
|
133
|
+
* first
|
134
|
+
* find
|
135
|
+
|
136
|
+
The `count` method only requires loading the first page of results, so it's a relatively cheap call. On the other hand,
|
137
|
+
`all` forces the entire collection to be loaded from John Deere's API, so use with caution. Organizations cannot be
|
138
|
+
created via the API, so there is no `create` method on this collection.
|
139
|
+
|
140
|
+
```ruby
|
141
|
+
client.organizations
|
142
|
+
# => collection of organizations under this client
|
143
|
+
|
144
|
+
client.organizations.count
|
145
|
+
# => 15
|
146
|
+
|
147
|
+
client.organizations.first
|
148
|
+
# => a single organization object
|
149
|
+
|
150
|
+
organization = client.organizations.find(1234)
|
151
|
+
# => a specific organization object, fetched by ID
|
152
|
+
|
153
|
+
organization.name
|
154
|
+
# => 'Smith Farms'
|
155
|
+
|
156
|
+
organization.type
|
157
|
+
# => 'customer'
|
158
|
+
|
159
|
+
organization.member
|
160
|
+
# => true
|
161
|
+
|
162
|
+
organization.links
|
163
|
+
# => {
|
164
|
+
# 'self' => 'https://sandboxapi.deere.com/platform/organizations/1234',
|
165
|
+
# 'machines' => 'https://sandboxapi.deere.com/platform/organizations/1234/machines',
|
166
|
+
# 'wdtCapableMachines' => 'ttps://sandboxapi.deere.com/platform/organizations/1234/machines?capability=wdt'
|
167
|
+
# }
|
168
|
+
|
169
|
+
```
|
170
|
+
|
171
|
+
This is much nicer than working with the raw API response:
|
172
|
+
|
173
|
+
```json
|
174
|
+
{
|
175
|
+
"links": [
|
176
|
+
{
|
177
|
+
"rel": "self",
|
178
|
+
"uri": "https://sandboxapi.deere.com/platform/organizations/1234"
|
179
|
+
},
|
180
|
+
{
|
181
|
+
"rel": "machines",
|
182
|
+
"uri": "https://sandboxapi.deere.com/platform/organizations/1234/machines"
|
183
|
+
},
|
184
|
+
{
|
185
|
+
"rel": "wdtCapableMachines",
|
186
|
+
"uri": "https://sandboxapi.deere.com/platform/organizations/1234/machines?capability=wdt"
|
187
|
+
}
|
188
|
+
],
|
189
|
+
"id": "1234",
|
190
|
+
"name": "Smith Farms",
|
191
|
+
"type": "customer",
|
192
|
+
"partnerships": [],
|
193
|
+
"member": true
|
194
|
+
}
|
195
|
+
```
|
196
|
+
|
197
|
+
But the real power comes from daisy-chaining associations together.
|
198
|
+
|
199
|
+
|
200
|
+
### [Assets](https://developer.deere.com/#!documentation&doc=.%2Fmyjohndeere%2Fassets.htm)
|
201
|
+
|
202
|
+
Handles an organization's assets. Supported methods:
|
203
|
+
|
204
|
+
* all
|
205
|
+
* count
|
206
|
+
* first
|
207
|
+
* find
|
208
|
+
* create
|
209
|
+
|
210
|
+
```ruby
|
211
|
+
organization = client.organizations.first
|
212
|
+
# => the first organization returned by the client
|
213
|
+
|
214
|
+
organization.assets
|
215
|
+
# => collection of assets
|
216
|
+
|
217
|
+
asset = organization.assets.find(123)
|
218
|
+
# => asset object, fetched by ID
|
219
|
+
|
220
|
+
asset.title
|
221
|
+
# => 'AgThing Water Device'
|
222
|
+
|
223
|
+
asset.category
|
224
|
+
# => 'DEVICE'
|
225
|
+
|
226
|
+
asset.type
|
227
|
+
# => 'SENSOR'
|
228
|
+
|
229
|
+
asset.sub_type
|
230
|
+
# => 'OTHER'
|
231
|
+
|
232
|
+
asset.links
|
233
|
+
# => a hash of API urls related to this asset
|
234
|
+
```
|
235
|
+
|
236
|
+
Creating an asset requires a contribution\_definition\_id, in addition to the attributes listed in the
|
237
|
+
[John Deere API docs](https://developer.deere.com/#!documentation). This method creates the asset in
|
238
|
+
the John Deere platform, and returns the newly created record.
|
239
|
+
|
240
|
+
```ruby
|
241
|
+
asset = organization.assets.create(
|
242
|
+
contribution_definition_id: ENV['CONTRIBUTION_DEFINITION_ID'],
|
243
|
+
title: 'Asset Title',
|
244
|
+
asset_category: 'DEVICE',
|
245
|
+
asset_type: 'SENSOR',
|
246
|
+
asset_sub_type: 'ENVIRONMENTAL'
|
247
|
+
)
|
248
|
+
|
249
|
+
asset.title
|
250
|
+
# => 'Asset Title'
|
251
|
+
```
|
252
|
+
|
253
|
+
|
117
254
|
### Direct API Requests
|
118
255
|
|
119
256
|
While the goal of the client is to eliminate the need to make/interpret calls to the John Deere API, it's important
|
data/test/support/vcr_setup.rb
CHANGED
@@ -141,14 +141,7 @@ class VcrSetup
|
|
141
141
|
title: 'Asset Title',
|
142
142
|
asset_category: 'DEVICE',
|
143
143
|
asset_type: 'SENSOR',
|
144
|
-
asset_sub_type: 'ENVIRONMENTAL'
|
145
|
-
links: [
|
146
|
-
{
|
147
|
-
'@type' => 'Link',
|
148
|
-
'rel' => 'contributionDefinition',
|
149
|
-
'uri' => "#{url}/contributionDefinitions/#{ENV['CONTRIBUTION_DEFINITION_ID']}"
|
150
|
-
}
|
151
|
-
]
|
144
|
+
asset_sub_type: 'ENVIRONMENTAL'
|
152
145
|
}.freeze
|
153
146
|
end
|
154
147
|
|