desk_api 0.6.0 → 0.6.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/LICENSE.txt +27 -0
- data/README.md +97 -61
- data/lib/desk.rb +29 -1
- data/lib/desk_api.rb +57 -5
- data/lib/desk_api/client.rb +104 -47
- data/lib/desk_api/configuration.rb +201 -108
- data/lib/desk_api/default.rb +109 -52
- data/lib/desk_api/error.rb +90 -40
- data/lib/desk_api/error/bad_gateway.rb +29 -1
- data/lib/desk_api/error/bad_request.rb +29 -1
- data/lib/desk_api/error/client_error.rb +31 -2
- data/lib/desk_api/error/configuration_error.rb +29 -1
- data/lib/desk_api/error/conflict.rb +29 -1
- data/lib/desk_api/error/follow_redirect_error.rb +42 -0
- data/lib/desk_api/error/forbidden.rb +29 -1
- data/lib/desk_api/error/gateway_timeout.rb +29 -1
- data/lib/desk_api/error/internal_server_error.rb +29 -1
- data/lib/desk_api/error/method_not_allowed.rb +29 -1
- data/lib/desk_api/error/not_acceptable.rb +29 -1
- data/lib/desk_api/error/not_found.rb +29 -1
- data/lib/desk_api/error/parser_error.rb +29 -1
- data/lib/desk_api/error/server_error.rb +29 -1
- data/lib/desk_api/error/service_unavailable.rb +29 -1
- data/lib/desk_api/error/too_many_requests.rb +29 -1
- data/lib/desk_api/error/unauthorized.rb +29 -1
- data/lib/desk_api/error/unprocessable_entity.rb +29 -1
- data/lib/desk_api/error/unsupported_media_type.rb +29 -1
- data/lib/desk_api/rate_limit.rb +63 -21
- data/lib/desk_api/request/encode_json.rb +49 -7
- data/lib/desk_api/request/oauth.rb +62 -14
- data/lib/desk_api/request/retry.rb +108 -34
- data/lib/desk_api/resource.rb +402 -192
- data/lib/desk_api/response/follow_redirects.rb +99 -0
- data/lib/desk_api/response/parse_dates.rb +63 -21
- data/lib/desk_api/response/parse_json.rb +47 -5
- data/lib/desk_api/response/raise_error.rb +51 -10
- data/lib/desk_api/version.rb +30 -2
- data/spec/cassettes/DeskApi_Resource/_update/can_handle_action_params.yml +110 -104
- data/spec/cassettes/DeskApi_Resource/_update/can_handle_links.yml +426 -0
- data/spec/desk_api/client_spec.rb +28 -0
- data/spec/desk_api/configuration_spec.rb +28 -0
- data/spec/desk_api/default_spec.rb +28 -0
- data/spec/desk_api/error_spec.rb +29 -1
- data/spec/desk_api/rate_limit_spec.rb +28 -0
- data/spec/desk_api/request/encode_json_spec.rb +28 -0
- data/spec/desk_api/request/oauth_spec.rb +28 -0
- data/spec/desk_api/request/retry_spec.rb +29 -1
- data/spec/desk_api/resource_spec.rb +49 -12
- data/spec/desk_api/response/follow_redirects_spec.rb +95 -0
- data/spec/desk_api/response/parse_dates_spec.rb +28 -0
- data/spec/desk_api/response/parse_json_spec.rb +56 -9
- data/spec/desk_api/response/raise_error_spec.rb +28 -0
- data/spec/desk_api_spec.rb +28 -0
- data/spec/spec_helper.rb +28 -0
- metadata +84 -24
- data/LICENSE +0 -7
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA1:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 418fce5029af0f83478582714488c4b29717deb2
|
4
|
+
data.tar.gz: 8be391f681e41a896d49ac74b64daa20878aacbc
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: bfd58a478541754852d65f8f66508354c51b9250fd26f77e157818905f592c4fa3ba654dcf58be463ed038e3037ffd5a244a613927e21b078d716fe5818260d8
|
7
|
+
data.tar.gz: 865c292b84e95f563311ba8dd3bd4dc8b73c60fca0bcc7319ffe6bd69db612b90438e4f50107227428d2ce3c7c30552e3d52a694e7918072d712e7045cfca6dc
|
data/LICENSE.txt
ADDED
@@ -0,0 +1,27 @@
|
|
1
|
+
Copyright (c) 2013-2014, Salesforce.com, Inc.
|
2
|
+
All rights reserved.
|
3
|
+
|
4
|
+
Redistribution and use in source and binary forms, with or without modification,
|
5
|
+
are permitted provided that the following conditions are met:
|
6
|
+
|
7
|
+
* Redistributions of source code must retain the above copyright notice, this
|
8
|
+
list of conditions and the following disclaimer.
|
9
|
+
|
10
|
+
* Redistributions in binary form must reproduce the above copyright notice,
|
11
|
+
this list of conditions and the following disclaimer in the documentation
|
12
|
+
and/or other materials provided with the distribution.
|
13
|
+
|
14
|
+
* Neither the name of Salesforce.com nor the names of its contributors may be
|
15
|
+
used to endorse or promote products derived from this software without
|
16
|
+
specific prior written permission.
|
17
|
+
|
18
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
19
|
+
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
20
|
+
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
21
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
|
22
|
+
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
23
|
+
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
24
|
+
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
|
25
|
+
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
26
|
+
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
27
|
+
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
data/README.md
CHANGED
@@ -1,12 +1,5 @@
|
|
1
1
|
# DeskApi a client for APIv2
|
2
|
-
|
3
|
-
[![Build Status](https://secure.travis-ci.org/tstachl/desk_api.png)](http://travis-ci.org/tstachl/desk_api)
|
4
|
-
[![Coverage Status](https://coveralls.io/repos/tstachl/desk_api/badge.png?branch=develop)](https://coveralls.io/r/tstachl/desk_api?branch=develop)
|
5
|
-
[![Dependency Status](https://gemnasium.com/tstachl/desk_api.png)](https://gemnasium.com/tstachl/desk_api)
|
6
|
-
|
7
|
-
___
|
8
|
-
## An Awesomely Unofficial Desk API Client
|
9
|
-
___
|
2
|
+
## An Awesomely (Un)official Desk API Client
|
10
3
|
|
11
4
|
DeskApi takes the capabilities of the Desk.com API and wraps them up in a Ruby
|
12
5
|
client so that it's easy-as-pie to get working with your support site's API.
|
@@ -14,28 +7,68 @@ client so that it's easy-as-pie to get working with your support site's API.
|
|
14
7
|
Desk publishes a changelog monthly, which you can keep up with at
|
15
8
|
[dev.desk.com/API/changelog](http://dev.desk.com/API/changelog).
|
16
9
|
|
17
|
-
We do our best to keep DeskApi, but please
|
18
|
-
|
19
|
-
|
10
|
+
We do our best to keep DeskApi, but please don't hesitate to open an
|
11
|
+
[issue](https://github.com/forcedotcom/salesforce-deskcom-api/issues) or send a
|
12
|
+
[pull request](https://github.com/forcedotcom/salesforce-deskcom-api/pulls)
|
13
|
+
if you find a bug or would like to new functionality added.
|
20
14
|
|
21
|
-
___
|
22
15
|
## Getting Started
|
23
|
-
___
|
24
|
-
|
25
16
|
### Installation
|
17
|
+
|
26
18
|
Easy!
|
27
19
|
|
28
20
|
```ruby
|
29
21
|
gem install desk_api
|
30
22
|
```
|
31
|
-
|
23
|
+
|
32
24
|
### Configuration
|
33
25
|
|
34
|
-
|
26
|
+
#### Authentication Mechanism
|
27
|
+
|
28
|
+
The desk.com API allows you to access data using two authentication mechanisms:
|
29
|
+
|
30
|
+
##### Basic Authentication
|
31
|
+
|
32
|
+
- Username
|
33
|
+
- Password
|
34
|
+
- Subdomain or Endpoint
|
35
|
+
|
36
|
+
##### OAuth 1.0a
|
37
|
+
|
38
|
+
- Consumer Key
|
39
|
+
- Consumer Secret
|
40
|
+
- Access Token
|
41
|
+
- Access Token Secret
|
42
|
+
- Subdomain or Endpoint
|
43
|
+
|
44
|
+
#### Trust is our #1 value
|
45
|
+
|
46
|
+
Whatever option or method you choose, please make sure to **never put your
|
47
|
+
credentials in your source code**. This makes them available to everyone
|
48
|
+
with read access to your source, it makes your code harder to maintain and
|
49
|
+
is just overall a bad idea. There are many alternatives, including configuration
|
50
|
+
files, environmental variables, ...
|
51
|
+
|
52
|
+
#### First Environmental Variables
|
53
|
+
|
54
|
+
`DeskApi` is automatically configured if you choose to use environmental
|
55
|
+
variables. There are 8 possible variables but you don't have to set all of them.
|
56
|
+
Based on the authentication mechanism you prefer you'll only have to specify:
|
57
|
+
|
58
|
+
```bash
|
59
|
+
export DESK_USERNAME=thomas@example.com
|
60
|
+
export DESK_PASSWORD=somepassword
|
61
|
+
export DESK_CONSUMER_KEY=CONSUMER_KEY
|
62
|
+
export DESK_CONSUMER_SECRET=CONSUMER_SECRET
|
63
|
+
export DESK_TOKEN=TOKEN
|
64
|
+
export DESK_TOKEN_SECRET=TOKEN_SECRET
|
65
|
+
export DESK_SUBDOMAIN=devel
|
66
|
+
export DESK_ENDPOINT=https://devel.desk.com
|
67
|
+
```
|
35
68
|
|
36
|
-
####
|
69
|
+
#### Second Configuration Option
|
37
70
|
|
38
|
-
Configure `DeskApi` itself to send/receive requests by calling the `configure`
|
71
|
+
Configure `DeskApi` itself to send/receive requests by calling the `configure`
|
39
72
|
method to set up your authentication credentials:
|
40
73
|
|
41
74
|
```ruby
|
@@ -59,7 +92,7 @@ DeskApi.patch '/api/v2/topics/1', name: 'Changed the Topic Name'
|
|
59
92
|
DeskApi.delete '/api/v2/topics/1'
|
60
93
|
```
|
61
94
|
|
62
|
-
####
|
95
|
+
#### Third Configuration Option
|
63
96
|
|
64
97
|
Initialize a new `DeskApi::Client` to send/receive requests
|
65
98
|
|
@@ -84,17 +117,13 @@ response = client.patch '/api/v2/topics/1', name: 'Changed the Topic Name'
|
|
84
117
|
response = client.delete '/api/v2/topics/1'
|
85
118
|
```
|
86
119
|
|
87
|
-
|
88
|
-
___
|
89
120
|
## Resources
|
90
|
-
___
|
91
121
|
|
92
122
|
Resources are automatically discovered by the DeskApi. When requesting a
|
93
123
|
resource from DeskAPI, the client sends the request and returns a
|
94
124
|
`DeskApi::Resource`. If the client receives an error back from the API a
|
95
125
|
`DeskApi::Error` is raised.
|
96
126
|
|
97
|
-
___
|
98
127
|
### Create Read Update Delete
|
99
128
|
|
100
129
|
One of the most important features; we support creating, updating and deleting
|
@@ -133,7 +162,7 @@ rescue DeskApi::Error::MethodNotAllowed => e
|
|
133
162
|
# too bad
|
134
163
|
end
|
135
164
|
```
|
136
|
-
|
165
|
+
|
137
166
|
### Getters & Setters
|
138
167
|
|
139
168
|
As you have seen in prior examples for each field on the resource we create a
|
@@ -161,7 +190,7 @@ rescue DeskApi::Error::MethodNotAllowed
|
|
161
190
|
# too bad
|
162
191
|
end
|
163
192
|
```
|
164
|
-
|
193
|
+
|
165
194
|
### Find
|
166
195
|
|
167
196
|
The method `by_url` can be called on the client, for backwards compatability we
|
@@ -187,7 +216,7 @@ collection `DeskApi.cases.find 1` the path will look like this:
|
|
187
216
|
| `DeskApi.cases.search(subject: 'Test').entries.find(1)` | `/api/v2/cases/1` |
|
188
217
|
| `DeskApi.cases.entries.first.replies.find(1)` | `/api/v2/cases/1/replies/1` |
|
189
218
|
| `DeskApi.cases.entries.first.replies.entries.first.find(1)` | `/api/v2/cases/1/replies/1` |
|
190
|
-
|
219
|
+
|
191
220
|
### Pagination
|
192
221
|
|
193
222
|
As mentioned above you can also navigate between resources and pages of
|
@@ -214,7 +243,7 @@ last_page = previous_page.last
|
|
214
243
|
# or go to the first page
|
215
244
|
first_page = last_page.first
|
216
245
|
```
|
217
|
-
|
246
|
+
|
218
247
|
### `all` and `each_page`
|
219
248
|
|
220
249
|
As a recent addition we made it even easier to navigate through all the pages.
|
@@ -231,7 +260,7 @@ end
|
|
231
260
|
|
232
261
|
Both methods use the max `per_page` for the API endpoint for that particular
|
233
262
|
resource.
|
234
|
-
|
263
|
+
|
235
264
|
### List params
|
236
265
|
|
237
266
|
Some lists allow for additional params like [cases](http://dev.desk.com/API/cases/#list).
|
@@ -248,7 +277,7 @@ customers_cases = DeskApi.cases(customer_id: 1)
|
|
248
277
|
# fetch cases for the filter with id 1
|
249
278
|
filters_cases = DeskApi.cases(filter_id: 1)
|
250
279
|
```
|
251
|
-
|
280
|
+
|
252
281
|
### Sorting
|
253
282
|
|
254
283
|
There is a maximum `page` limit on some Desk.com API endpoints. As of right now
|
@@ -271,11 +300,13 @@ To work around page limits, you can specify `sort_field` and `sort_direction`
|
|
271
300
|
# fetch cases sorted by updated_at direction desc
|
272
301
|
sorted_cases = DeskApi.cases(sort_field: :updated_at, sort_direction: :desc)
|
273
302
|
```
|
274
|
-
|
303
|
+
|
275
304
|
### Links
|
276
305
|
|
277
|
-
Once a `DeskApi::Resource` has loaded, its
|
278
|
-
|
306
|
+
Once a `DeskApi::Resource` has loaded, its
|
307
|
+
[linked resources](http://dev.desk.com/API/using-the-api/#relationships)
|
308
|
+
can be retrieved by calling the linked resource as a method of the
|
309
|
+
`DeskApi::Resource`, e.g.,
|
279
310
|
|
280
311
|
```ruby
|
281
312
|
# Get a ticket
|
@@ -302,7 +333,7 @@ user_name = DeskApi.
|
|
302
333
|
sent_by.
|
303
334
|
name
|
304
335
|
```
|
305
|
-
|
336
|
+
|
306
337
|
### Lazy loading
|
307
338
|
|
308
339
|
Resources are lazy loaded. This means that requests are only sent when you
|
@@ -318,12 +349,13 @@ end
|
|
318
349
|
# it'll send a request
|
319
350
|
DeskApi.cases.page == 1
|
320
351
|
```
|
321
|
-
|
352
|
+
|
322
353
|
### Embedding
|
323
354
|
|
324
|
-
Some endpoints support [embedding](http://dev.desk.com/API/using-the-api/#embedding)
|
325
|
-
of cases from `/api/v2/cases` you
|
326
|
-
`embed=` to the query
|
355
|
+
Some endpoints support [embedding](http://dev.desk.com/API/using-the-api/#embedding)
|
356
|
+
related resources. E.g., when getting a list of cases from `/api/v2/cases` you
|
357
|
+
can embed the customer on each case by adding `embed=` to the query
|
358
|
+
string: `/api/v2/cases?embed=customer`
|
327
359
|
|
328
360
|
The client supports this: `tickets_and_customers = DeskApi.cases.embed(:customer)`
|
329
361
|
|
@@ -361,7 +393,7 @@ customer = my_case.customer
|
|
361
393
|
assigned_user = my_case.assigned_user
|
362
394
|
assigned_group = my_case.assigned_group
|
363
395
|
```
|
364
|
-
|
396
|
+
|
365
397
|
### API Errors
|
366
398
|
|
367
399
|
Sometimes the API is going to return errors, eg. Validation Error. In these
|
@@ -384,28 +416,32 @@ Please also have a look at all
|
|
384
416
|
[desk.com API errors](http://dev.desk.com/API/using-the-api/#status-codes) and
|
385
417
|
their respective meanings.
|
386
418
|
|
387
|
-
___
|
388
419
|
## License
|
389
|
-
___
|
390
|
-
|
391
|
-
(The MIT License)
|
392
|
-
|
393
|
-
Copyright (c) 2013-2014 Thomas Stachl <tstachl@salesforce.com>
|
394
|
-
|
395
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy of
|
396
|
-
this software and associated documentation files (the 'Software'), to deal in
|
397
|
-
the Software without restriction, including without limitation the rights to
|
398
|
-
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
|
399
|
-
the Software, and to permit persons to whom the Software is furnished to do so,
|
400
|
-
subject to the following conditions:
|
401
|
-
|
402
|
-
The above copyright notice and this permission notice shall be included in all
|
403
|
-
copies or substantial portions of the Software.
|
404
420
|
|
405
|
-
|
406
|
-
|
407
|
-
|
408
|
-
|
409
|
-
|
410
|
-
|
411
|
-
|
421
|
+
Copyright (c) 2013-2014, Salesforce.com, Inc.
|
422
|
+
All rights reserved.
|
423
|
+
|
424
|
+
Redistribution and use in source and binary forms, with or without modification,
|
425
|
+
are permitted provided that the following conditions are met:
|
426
|
+
|
427
|
+
* Redistributions of source code must retain the above copyright notice, this
|
428
|
+
list of conditions and the following disclaimer.
|
429
|
+
|
430
|
+
* Redistributions in binary form must reproduce the above copyright notice,
|
431
|
+
this list of conditions and the following disclaimer in the documentation
|
432
|
+
and/or other materials provided with the distribution.
|
433
|
+
|
434
|
+
* Neither the name of Salesforce.com nor the names of its contributors may be
|
435
|
+
used to endorse or promote products derived from this software without
|
436
|
+
specific prior written permission.
|
437
|
+
|
438
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
439
|
+
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
440
|
+
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
441
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
|
442
|
+
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
443
|
+
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
444
|
+
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
|
445
|
+
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
446
|
+
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
447
|
+
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
data/lib/desk.rb
CHANGED
@@ -1 +1,29 @@
|
|
1
|
-
|
1
|
+
# Copyright (c) 2013-2014, Salesforce.com, Inc.
|
2
|
+
# All rights reserved.
|
3
|
+
#
|
4
|
+
# Redistribution and use in source and binary forms, with or without modification,
|
5
|
+
# are permitted provided that the following conditions are met:
|
6
|
+
#
|
7
|
+
# * Redistributions of source code must retain the above copyright notice, this
|
8
|
+
# list of conditions and the following disclaimer.
|
9
|
+
#
|
10
|
+
# * Redistributions in binary form must reproduce the above copyright notice,
|
11
|
+
# this list of conditions and the following disclaimer in the documentation
|
12
|
+
# and/or other materials provided with the distribution.
|
13
|
+
#
|
14
|
+
# * Neither the name of Salesforce.com nor the names of its contributors may be
|
15
|
+
# used to endorse or promote products derived from this software without
|
16
|
+
# specific prior written permission.
|
17
|
+
#
|
18
|
+
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
19
|
+
# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
20
|
+
# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
21
|
+
# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
|
22
|
+
# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
23
|
+
# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
24
|
+
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
|
25
|
+
# ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
26
|
+
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
27
|
+
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
28
|
+
|
29
|
+
require File.dirname(__FILE__) + '/desk_api'
|
data/lib/desk_api.rb
CHANGED
@@ -1,8 +1,55 @@
|
|
1
|
+
# Copyright (c) 2013-2014, Salesforce.com, Inc.
|
2
|
+
# All rights reserved.
|
3
|
+
#
|
4
|
+
# Redistribution and use in source and binary forms, with or without modification,
|
5
|
+
# are permitted provided that the following conditions are met:
|
6
|
+
#
|
7
|
+
# * Redistributions of source code must retain the above copyright notice, this
|
8
|
+
# list of conditions and the following disclaimer.
|
9
|
+
#
|
10
|
+
# * Redistributions in binary form must reproduce the above copyright notice,
|
11
|
+
# this list of conditions and the following disclaimer in the documentation
|
12
|
+
# and/or other materials provided with the distribution.
|
13
|
+
#
|
14
|
+
# * Neither the name of Salesforce.com nor the names of its contributors may be
|
15
|
+
# used to endorse or promote products derived from this software without
|
16
|
+
# specific prior written permission.
|
17
|
+
#
|
18
|
+
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
19
|
+
# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
20
|
+
# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
21
|
+
# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
|
22
|
+
# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
23
|
+
# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
24
|
+
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
|
25
|
+
# ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
26
|
+
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
27
|
+
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
28
|
+
|
1
29
|
require 'uri'
|
2
30
|
require 'faraday'
|
3
31
|
require 'forwardable'
|
4
32
|
require 'addressable/uri'
|
5
33
|
|
34
|
+
# {DeskApi} allows for easy interaction with Desk.com's API.
|
35
|
+
# It is the top level namespace and delegates all missing
|
36
|
+
# methods to an automatically created client. This allows
|
37
|
+
# you to use {DeskApi} as a client which is not recommended
|
38
|
+
# if you have to connect to multiple Desk.com sites.
|
39
|
+
#
|
40
|
+
# @author Thomas Stachl <tstachl@salesforce.com>
|
41
|
+
# @copyright Copyright (c) 2013-2014 Salesforce.com
|
42
|
+
# @license BSD 3-Clause License
|
43
|
+
#
|
44
|
+
# @example configure the {DeskApi} client
|
45
|
+
# DeskApi.configure |config|
|
46
|
+
# config.username = 'user@example.com'
|
47
|
+
# config.password = 'mysecretpassword'
|
48
|
+
# config.endpoint = 'https://example.desk.com'
|
49
|
+
# end
|
50
|
+
#
|
51
|
+
# @example use {DeskApi} to send requests
|
52
|
+
# my_cases = DeskApi.cases # GET '/api/v2/cases'
|
6
53
|
module DeskApi
|
7
54
|
require 'desk_api/version'
|
8
55
|
require 'desk_api/configuration'
|
@@ -11,18 +58,23 @@ module DeskApi
|
|
11
58
|
class << self
|
12
59
|
include DeskApi::Configuration
|
13
60
|
|
14
|
-
#
|
61
|
+
# Returns the default {DeskApi::Client}
|
15
62
|
#
|
63
|
+
# @param options [Hash] optional configuration options
|
16
64
|
# @return [DeskApi::Client]
|
17
65
|
def client
|
18
|
-
return @client if
|
66
|
+
return @client if defined?(:@client) && @client.hash == options.hash
|
19
67
|
@client = DeskApi::Client.new(options)
|
20
68
|
end
|
21
69
|
|
22
|
-
|
23
|
-
|
70
|
+
# Delegates missing methods to the default {DeskApi::Client}
|
71
|
+
#
|
72
|
+
# @return [DeskApi::Resource]
|
73
|
+
def method_missing(method, *args, &block)
|
74
|
+
client.send(method, *args, &block)
|
24
75
|
end
|
25
76
|
end
|
26
77
|
|
27
|
-
|
78
|
+
# immediately reset the default client
|
79
|
+
reset!
|
28
80
|
end
|
data/lib/desk_api/client.rb
CHANGED
@@ -1,61 +1,118 @@
|
|
1
|
+
# Copyright (c) 2013-2014, Salesforce.com, Inc.
|
2
|
+
# All rights reserved.
|
3
|
+
#
|
4
|
+
# Redistribution and use in source and binary forms, with or without modification,
|
5
|
+
# are permitted provided that the following conditions are met:
|
6
|
+
#
|
7
|
+
# * Redistributions of source code must retain the above copyright notice, this
|
8
|
+
# list of conditions and the following disclaimer.
|
9
|
+
#
|
10
|
+
# * Redistributions in binary form must reproduce the above copyright notice,
|
11
|
+
# this list of conditions and the following disclaimer in the documentation
|
12
|
+
# and/or other materials provided with the distribution.
|
13
|
+
#
|
14
|
+
# * Neither the name of Salesforce.com nor the names of its contributors may be
|
15
|
+
# used to endorse or promote products derived from this software without
|
16
|
+
# specific prior written permission.
|
17
|
+
#
|
18
|
+
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
19
|
+
# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
20
|
+
# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
21
|
+
# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
|
22
|
+
# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
23
|
+
# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
24
|
+
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
|
25
|
+
# ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
26
|
+
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
27
|
+
# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
28
|
+
|
1
29
|
require 'desk_api/resource'
|
2
30
|
require 'desk_api/error/parser_error'
|
3
31
|
|
4
|
-
|
5
|
-
|
6
|
-
|
7
|
-
#
|
32
|
+
module DeskApi
|
33
|
+
# The {DeskApi::Client} builds and performs the
|
34
|
+
# http request using Faraday and the configured
|
35
|
+
# adapter. It includes and has full access to
|
36
|
+
# the configuration module.
|
8
37
|
#
|
9
|
-
# @
|
10
|
-
# @
|
11
|
-
|
12
|
-
|
13
|
-
|
14
|
-
end
|
15
|
-
end
|
38
|
+
# @author Thomas Stachl <tstachl@salesforce.com>
|
39
|
+
# @copyright Copyright (c) 2013-2014 Salesforce.com
|
40
|
+
# @license BSD 3-Clause License
|
41
|
+
class Client
|
42
|
+
include DeskApi::Configuration
|
16
43
|
|
17
|
-
|
18
|
-
|
19
|
-
|
20
|
-
|
21
|
-
|
22
|
-
|
23
|
-
|
24
|
-
|
25
|
-
|
44
|
+
# Initializes a new client object
|
45
|
+
#
|
46
|
+
# @param options [Hash] optional configuration hash
|
47
|
+
# @return [DeskApi::Client] the new client
|
48
|
+
def initialize(options = {})
|
49
|
+
DeskApi::Configuration.keys.each do |key|
|
50
|
+
value = options[key] || DeskApi.instance_variable_get(:"@#{key}")
|
51
|
+
instance_variable_set(:"@#{key}", value)
|
52
|
+
end
|
53
|
+
end
|
26
54
|
|
27
|
-
|
28
|
-
|
29
|
-
|
30
|
-
|
55
|
+
# Perform an http request
|
56
|
+
#
|
57
|
+
# @param path [String] the url path to the resource
|
58
|
+
# @param params [Hash] optional additional url params
|
59
|
+
# @yield [Faraday::Response] for further request customizations.
|
60
|
+
# @return [Faraday::Response]
|
61
|
+
%w(get head delete post patch).each do |method|
|
62
|
+
class_eval <<-RUBY, __FILE__, __LINE__ + 1
|
63
|
+
def #{method}(path, params = {}, &block)
|
64
|
+
request(:#{method}, path, params, &block)
|
65
|
+
end
|
66
|
+
RUBY
|
67
|
+
end
|
31
68
|
|
32
|
-
|
33
|
-
|
34
|
-
|
35
|
-
|
69
|
+
# Returns a new resource for the given path
|
70
|
+
#
|
71
|
+
# @param path [String] the url path to the resource
|
72
|
+
# @return [DeskApi::Resource]
|
73
|
+
def by_url(path)
|
74
|
+
DeskApi::Resource.new(self, DeskApi::Resource.build_self_link(path))
|
75
|
+
end
|
36
76
|
|
37
|
-
|
38
|
-
def by_url(url)
|
39
|
-
DeskApi::Resource.new(self, DeskApi::Resource.build_self_link(url))
|
40
|
-
end
|
77
|
+
private
|
41
78
|
|
42
|
-
|
43
|
-
|
44
|
-
|
45
|
-
|
46
|
-
|
79
|
+
# Returns a new resource based on the method you're trying to load:
|
80
|
+
#
|
81
|
+
# @example request cases
|
82
|
+
# my_cases = client.cases # GET '/api/v2/cases'
|
83
|
+
# @param method [Symbol] the method called
|
84
|
+
# @param params [Hash] additional query params
|
85
|
+
# @yield [DeskApi::Resource]
|
86
|
+
# @return [DeskApi::Resource]
|
87
|
+
def method_missing(method, params = {})
|
88
|
+
definition = DeskApi::Resource.build_self_link("/api/v2/#{method}")
|
89
|
+
DeskApi::Resource.new(self, definition).tap do |res|
|
90
|
+
res.query_params = params
|
91
|
+
yield res if block_given?
|
92
|
+
end
|
47
93
|
end
|
48
|
-
end
|
49
94
|
|
50
|
-
|
51
|
-
|
52
|
-
|
53
|
-
|
54
|
-
|
55
|
-
|
56
|
-
|
95
|
+
# Hands off the request to Faraday for further processing
|
96
|
+
#
|
97
|
+
# @param method [Symbol] the http method to call
|
98
|
+
# @param path [String] the url path to the resource
|
99
|
+
# @param params [Hash] optional additional url params
|
100
|
+
# @yield [Faraday::Response] for further request customizations.
|
101
|
+
# @return [Faraday::Response]
|
102
|
+
# @raises [DeskApi::Error::ClientError]
|
103
|
+
# @raises [DeskApi::Error::ParserError]
|
104
|
+
def request(method, path, params = {}, &block)
|
105
|
+
connection.send(method, path, params, &block)
|
106
|
+
rescue Faraday::Error::ClientError
|
107
|
+
raise DeskApi::Error::ClientError
|
108
|
+
rescue JSON::ParserError
|
109
|
+
raise DeskApi::Error::ParserError
|
110
|
+
end
|
57
111
|
|
58
|
-
|
59
|
-
@
|
112
|
+
# Builds and/or returns the Faraday client.
|
113
|
+
# @returns [Faraday::Connection]
|
114
|
+
def connection
|
115
|
+
@connection ||= Faraday.new endpoint, connection_options, &middleware
|
116
|
+
end
|
60
117
|
end
|
61
118
|
end
|