md-notes-resource 1.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/LICENSE +28 -0
- data/README.md +460 -0
- data/lib/md_notes.rb +45 -0
- data/lib/md_notes/api_helper.rb +289 -0
- data/lib/md_notes/client.rb +61 -0
- data/lib/md_notes/configuration.rb +157 -0
- data/lib/md_notes/controllers/base_controller.rb +49 -0
- data/lib/md_notes/controllers/o_auth_authorization_controller.rb +140 -0
- data/lib/md_notes/controllers/service_controller.rb +40 -0
- data/lib/md_notes/controllers/user_controller.rb +40 -0
- data/lib/md_notes/exceptions/api_exception.rb +20 -0
- data/lib/md_notes/exceptions/o_auth_provider_exception.rb +44 -0
- data/lib/md_notes/http/auth/o_auth2.rb +78 -0
- data/lib/md_notes/http/faraday_client.rb +70 -0
- data/lib/md_notes/http/http_call_back.rb +24 -0
- data/lib/md_notes/http/http_client.rb +104 -0
- data/lib/md_notes/http/http_method_enum.rb +13 -0
- data/lib/md_notes/http/http_request.rb +50 -0
- data/lib/md_notes/http/http_response.rb +29 -0
- data/lib/md_notes/models/base_model.rb +54 -0
- data/lib/md_notes/models/note.rb +90 -0
- data/lib/md_notes/models/o_auth_provider_error_enum.rb +39 -0
- data/lib/md_notes/models/o_auth_token.rb +92 -0
- data/lib/md_notes/models/service_status.rb +108 -0
- data/lib/md_notes/models/user.rb +81 -0
- data/lib/md_notes/utilities/file_wrapper.rb +17 -0
- metadata +151 -0
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA256:
|
3
|
+
metadata.gz: 7ac7a3cdecb046dae4b20024a4b1bf9a135bf1638cf8c9f7c3c3529163f548a7
|
4
|
+
data.tar.gz: 730cc3203421e929e9b7084b80d62b7cd291b1b602c06036745592c1658bdf46
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: 467f97b086cd735ba9bbcb74c4fcf9f8461d37c34be36a19c8f57432990a69f97db1b16057b0599629e5952d1568f139e45898325e95cee3005a75780112b395
|
7
|
+
data.tar.gz: 731ab35415894aeecd341935025c189f3707ab92191aaeb8f8aebc884e64fffab7f51d2babe92b405d47a10426d9537870593635e21a784ea865f673407b4dab
|
data/LICENSE
ADDED
@@ -0,0 +1,28 @@
|
|
1
|
+
License:
|
2
|
+
========
|
3
|
+
The MIT License (MIT)
|
4
|
+
http://opensource.org/licenses/MIT
|
5
|
+
|
6
|
+
Copyright (c) 2014 - 2020 APIMATIC Limited
|
7
|
+
|
8
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
9
|
+
of this software and associated documentation files (the "Software"), to deal
|
10
|
+
in the Software without restriction, including without limitation the rights
|
11
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
12
|
+
copies of the Software, and to permit persons to whom the Software is
|
13
|
+
furnished to do so, subject to the following conditions:
|
14
|
+
|
15
|
+
The above copyright notice and this permission notice shall be included in
|
16
|
+
all copies or substantial portions of the Software.
|
17
|
+
|
18
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
19
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
20
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
21
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
22
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
23
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
24
|
+
THE SOFTWARE.
|
25
|
+
|
26
|
+
Trade Mark:
|
27
|
+
==========
|
28
|
+
APIMATIC is a trade mark for APIMATIC Limited
|
data/README.md
ADDED
@@ -0,0 +1,460 @@
|
|
1
|
+
# Getting Started with MdNotes
|
2
|
+
|
3
|
+
## Getting Started
|
4
|
+
|
5
|
+
### Introduction
|
6
|
+
|
7
|
+
API for Markdown Notes app.
|
8
|
+
|
9
|
+
### Install the Package
|
10
|
+
|
11
|
+
Install the gem from the command line:
|
12
|
+
|
13
|
+
```ruby
|
14
|
+
gem install md-notes-resource -v 1.0
|
15
|
+
```
|
16
|
+
|
17
|
+
Or add the gem to your Gemfile and run `bundle`:
|
18
|
+
|
19
|
+
```ruby
|
20
|
+
gem 'md-notes-resource', '1.0'
|
21
|
+
```
|
22
|
+
|
23
|
+
For additional gem details, see the [RubyGems page for the md-notes-resource gem](https://rubygems.org/gems/md-notes-resource/versions/1.0).
|
24
|
+
|
25
|
+
### Initialize the API Client
|
26
|
+
|
27
|
+
The following parameters are configurable for the API Client:
|
28
|
+
|
29
|
+
| Parameter | Type | Description |
|
30
|
+
| --- | --- | --- |
|
31
|
+
| `o_auth_client_id` | `String` | OAuth 2 Client ID |
|
32
|
+
| `o_auth_client_secret` | `String` | OAuth 2 Client Secret |
|
33
|
+
| `o_auth_username` | `String` | OAuth 2 Resource Owner Username |
|
34
|
+
| `o_auth_password` | `String` | OAuth 2 Resource Owner Password |
|
35
|
+
| `timeout` | `Float` | The value to use for connection timeout. <br> **Default: 60** |
|
36
|
+
| `max_retries` | `Integer` | The number of times to retry an endpoint call if it fails. <br> **Default: 0** |
|
37
|
+
| `retry_interval` | `Float` | Pause in seconds between retries. <br> **Default: 1** |
|
38
|
+
| `backoff_factor` | `Float` | The amount to multiply each successive retry's interval amount by in order to provide backoff. <br> **Default: 2** |
|
39
|
+
| `retry_statuses` | `Array` | A list of HTTP statuses to retry. <br> **Default: [408, 413, 429, 500, 502, 503, 504, 521, 522, 524]** |
|
40
|
+
| `retry_methods` | `Array` | A list of HTTP methods to retry. <br> **Default: %i[get put]** |
|
41
|
+
| `o_auth_token` | `OAuthToken` | Object for storing information about the OAuth token |
|
42
|
+
|
43
|
+
The API client can be initialized as follows:
|
44
|
+
|
45
|
+
```ruby
|
46
|
+
client = MdNotes::Client.new(
|
47
|
+
o_auth_client_id: 'OAuthClientId',
|
48
|
+
o_auth_client_secret: 'OAuthClientSecret',
|
49
|
+
o_auth_username: 'OAuthUsername',
|
50
|
+
o_auth_password: 'OAuthPassword',
|
51
|
+
)
|
52
|
+
```
|
53
|
+
|
54
|
+
### Authorization
|
55
|
+
|
56
|
+
The SDK will attempt to authorize by providing no scopes in case an endpoint requiring authentication is called. You can also authorize the client yourself.
|
57
|
+
|
58
|
+
Your application must obtain user authorization before it can execute an endpoint call. The SDK uses *OAuth 2.0 Authorization* to authorize the client.
|
59
|
+
|
60
|
+
The `authorize()` method will exchange the user's credentials for an *access token*. The access token is an object containing information for authorizing client requests and refreshing the token itself.
|
61
|
+
|
62
|
+
```ruby
|
63
|
+
begin
|
64
|
+
client.auth.authorize()
|
65
|
+
rescue OAuthProviderException => ex
|
66
|
+
# handle exception
|
67
|
+
rescue APIException => ex
|
68
|
+
# handle exception
|
69
|
+
end
|
70
|
+
```
|
71
|
+
|
72
|
+
The client can now make authorized endpoint calls.
|
73
|
+
|
74
|
+
#### Refreshing the token
|
75
|
+
|
76
|
+
An access token may expire after sometime. To extend its lifetime, you must refresh the token.
|
77
|
+
|
78
|
+
```ruby
|
79
|
+
if client.auth.is_token_expired
|
80
|
+
begin
|
81
|
+
client.auth.refresh_token
|
82
|
+
rescue OAuthProviderException => ex
|
83
|
+
# handle exception
|
84
|
+
end
|
85
|
+
end
|
86
|
+
```
|
87
|
+
|
88
|
+
If a token expires, the SDK will attempt to automatically refresh the token before the next endpoint call requiring authentication.
|
89
|
+
|
90
|
+
#### Storing an access token for reuse
|
91
|
+
|
92
|
+
It is recommended that you store the access token for reuse.
|
93
|
+
|
94
|
+
```ruby
|
95
|
+
# store token
|
96
|
+
save_token_to_database(client.config.o_auth_token)
|
97
|
+
```
|
98
|
+
|
99
|
+
#### Creating a client from a stored token
|
100
|
+
|
101
|
+
To authorize a client from a stored access token, just set the access token in Configuration along with the other configuration parameters before creating the client:
|
102
|
+
|
103
|
+
```ruby
|
104
|
+
# load token later...
|
105
|
+
client.config.o_auth_token = load_token_from_database
|
106
|
+
|
107
|
+
# Set other configuration, then instantiate client
|
108
|
+
client = Client.new
|
109
|
+
```
|
110
|
+
|
111
|
+
#### Complete example
|
112
|
+
|
113
|
+
```ruby
|
114
|
+
require 'md_notes'
|
115
|
+
|
116
|
+
include md_notes
|
117
|
+
|
118
|
+
# function for storing token to database
|
119
|
+
def save_token_to_database(token)
|
120
|
+
# code to save the token to database
|
121
|
+
end
|
122
|
+
|
123
|
+
# function for loading token from database
|
124
|
+
def load_token_from_database
|
125
|
+
# load token from database and return it (return nil if no token exists)
|
126
|
+
end
|
127
|
+
|
128
|
+
# create a new client
|
129
|
+
client = MdNotes::Client.new(
|
130
|
+
o_auth_client_id: 'OAuthClientId',
|
131
|
+
o_auth_client_secret: 'OAuthClientSecret',
|
132
|
+
o_auth_username: 'OAuthUsername',
|
133
|
+
o_auth_password: 'OAuthPassword',
|
134
|
+
)
|
135
|
+
|
136
|
+
# obtain access token, needed for client to be authorized
|
137
|
+
previous_token = load_token_from_database
|
138
|
+
if previous_token
|
139
|
+
# restore previous access token
|
140
|
+
client.config.o_auth_token = previous_token
|
141
|
+
else
|
142
|
+
# obtain new access token
|
143
|
+
begin
|
144
|
+
client.auth.authorize()
|
145
|
+
rescue OAuthProviderException => ex
|
146
|
+
# handle exception
|
147
|
+
rescue APIException => ex
|
148
|
+
# handle exception
|
149
|
+
end
|
150
|
+
end
|
151
|
+
|
152
|
+
# the client is now authorized; you can use client to make endpoint calls
|
153
|
+
# client will automatically refresh the token when it expires and call the token update callback
|
154
|
+
```
|
155
|
+
|
156
|
+
## Client Class Documentation
|
157
|
+
|
158
|
+
### MdNotes Client
|
159
|
+
|
160
|
+
The gateway for the SDK. This class acts as a factory for the Controllers and also holds the configuration of the SDK.
|
161
|
+
|
162
|
+
### Controllers
|
163
|
+
|
164
|
+
| Name | Description |
|
165
|
+
| --- | --- |
|
166
|
+
| service | Gets ServiceController |
|
167
|
+
| user | Gets UserController |
|
168
|
+
| o_auth_authorization | Gets OAuthAuthorizationController |
|
169
|
+
|
170
|
+
## API Reference
|
171
|
+
|
172
|
+
### List of APIs
|
173
|
+
|
174
|
+
* [Service](#service)
|
175
|
+
* [User](#user)
|
176
|
+
|
177
|
+
### Service
|
178
|
+
|
179
|
+
#### Overview
|
180
|
+
|
181
|
+
##### Get instance
|
182
|
+
|
183
|
+
An instance of the `ServiceController` class can be accessed from the API Client.
|
184
|
+
|
185
|
+
```
|
186
|
+
service_controller = client.service
|
187
|
+
```
|
188
|
+
|
189
|
+
#### Get Status
|
190
|
+
|
191
|
+
```ruby
|
192
|
+
def get_status
|
193
|
+
```
|
194
|
+
|
195
|
+
##### Response Type
|
196
|
+
|
197
|
+
[`ServiceStatus`](#service-status)
|
198
|
+
|
199
|
+
##### Example Usage
|
200
|
+
|
201
|
+
```ruby
|
202
|
+
result = service_controller.get_status()
|
203
|
+
```
|
204
|
+
|
205
|
+
### User
|
206
|
+
|
207
|
+
#### Overview
|
208
|
+
|
209
|
+
##### Get instance
|
210
|
+
|
211
|
+
An instance of the `UserController` class can be accessed from the API Client.
|
212
|
+
|
213
|
+
```
|
214
|
+
user_controller = client.user
|
215
|
+
```
|
216
|
+
|
217
|
+
#### Get User
|
218
|
+
|
219
|
+
```ruby
|
220
|
+
def get_user
|
221
|
+
```
|
222
|
+
|
223
|
+
##### Response Type
|
224
|
+
|
225
|
+
[`User`](#user-1)
|
226
|
+
|
227
|
+
##### Example Usage
|
228
|
+
|
229
|
+
```ruby
|
230
|
+
result = user_controller.get_user()
|
231
|
+
```
|
232
|
+
|
233
|
+
## Model Reference
|
234
|
+
|
235
|
+
### Structures
|
236
|
+
|
237
|
+
* [Note](#note)
|
238
|
+
* [User](#user-1)
|
239
|
+
* [Service Status](#service-status)
|
240
|
+
* [O Auth Token](#o-auth-token)
|
241
|
+
|
242
|
+
#### Note
|
243
|
+
|
244
|
+
##### Class Name
|
245
|
+
|
246
|
+
`Note`
|
247
|
+
|
248
|
+
##### Fields
|
249
|
+
|
250
|
+
| Name | Type | Tags | Description |
|
251
|
+
| --- | --- | --- | --- |
|
252
|
+
| `id` | `Long` | Required | - |
|
253
|
+
| `title` | `String` | Required | - |
|
254
|
+
| `body` | `String` | Required | - |
|
255
|
+
| `user_id` | `Long` | Required | - |
|
256
|
+
| `created_at` | `String` | Required | - |
|
257
|
+
| `updated_at` | `String` | Required | - |
|
258
|
+
|
259
|
+
##### Example (as JSON)
|
260
|
+
|
261
|
+
```json
|
262
|
+
{
|
263
|
+
"id": 112,
|
264
|
+
"title": "title4",
|
265
|
+
"body": "body6",
|
266
|
+
"user_id": 208,
|
267
|
+
"created_at": "created_at2",
|
268
|
+
"updated_at": "updated_at4"
|
269
|
+
}
|
270
|
+
```
|
271
|
+
|
272
|
+
#### User
|
273
|
+
|
274
|
+
##### Class Name
|
275
|
+
|
276
|
+
`User`
|
277
|
+
|
278
|
+
##### Fields
|
279
|
+
|
280
|
+
| Name | Type | Tags | Description |
|
281
|
+
| --- | --- | --- | --- |
|
282
|
+
| `id` | `Integer` | Required | - |
|
283
|
+
| `name` | `String` | Required | - |
|
284
|
+
| `email` | `String` | Required | - |
|
285
|
+
| `created_at` | `String` | Required | - |
|
286
|
+
| `updated_at` | `String` | Required | - |
|
287
|
+
|
288
|
+
##### Example (as JSON)
|
289
|
+
|
290
|
+
```json
|
291
|
+
{
|
292
|
+
"id": 112,
|
293
|
+
"name": "name0",
|
294
|
+
"email": "email6",
|
295
|
+
"created_at": "created_at2",
|
296
|
+
"updated_at": "updated_at4"
|
297
|
+
}
|
298
|
+
```
|
299
|
+
|
300
|
+
#### Service Status
|
301
|
+
|
302
|
+
##### Class Name
|
303
|
+
|
304
|
+
`ServiceStatus`
|
305
|
+
|
306
|
+
##### Fields
|
307
|
+
|
308
|
+
| Name | Type | Tags | Description |
|
309
|
+
| --- | --- | --- | --- |
|
310
|
+
| `app` | `String` | Required | - |
|
311
|
+
| `moto` | `String` | Required | - |
|
312
|
+
| `notes` | `Integer` | Required | - |
|
313
|
+
| `users` | `Integer` | Required | - |
|
314
|
+
| `time` | `String` | Required | - |
|
315
|
+
| `os` | `String` | Required | - |
|
316
|
+
| `php_version` | `String` | Required | - |
|
317
|
+
| `status` | `String` | Required | - |
|
318
|
+
|
319
|
+
##### Example (as JSON)
|
320
|
+
|
321
|
+
```json
|
322
|
+
{
|
323
|
+
"app": "app2",
|
324
|
+
"moto": "moto8",
|
325
|
+
"notes": 134,
|
326
|
+
"users": 202,
|
327
|
+
"time": "time0",
|
328
|
+
"os": "os8",
|
329
|
+
"php_version": "php_version4",
|
330
|
+
"status": "status8"
|
331
|
+
}
|
332
|
+
```
|
333
|
+
|
334
|
+
#### O Auth Token
|
335
|
+
|
336
|
+
OAuth 2 Authorization endpoint response
|
337
|
+
|
338
|
+
##### Class Name
|
339
|
+
|
340
|
+
`OAuthToken`
|
341
|
+
|
342
|
+
##### Fields
|
343
|
+
|
344
|
+
| Name | Type | Tags | Description |
|
345
|
+
| --- | --- | --- | --- |
|
346
|
+
| `access_token` | `String` | Required | Access token |
|
347
|
+
| `token_type` | `String` | Required | Type of access token |
|
348
|
+
| `expires_in` | `Long` | Optional | Time in seconds before the access token expires |
|
349
|
+
| `scope` | `String` | Optional | List of scopes granted<br>This is a space-delimited list of strings. |
|
350
|
+
| `expiry` | `Long` | Optional | Time of token expiry as unix timestamp (UTC) |
|
351
|
+
| `refresh_token` | `String` | Optional | Refresh token<br>Used to get a new access token when it expires. |
|
352
|
+
|
353
|
+
##### Example (as JSON)
|
354
|
+
|
355
|
+
```json
|
356
|
+
{
|
357
|
+
"access_token": "access_token8",
|
358
|
+
"token_type": "token_type2",
|
359
|
+
"expires_in": null,
|
360
|
+
"scope": null,
|
361
|
+
"expiry": null,
|
362
|
+
"refresh_token": null
|
363
|
+
}
|
364
|
+
```
|
365
|
+
|
366
|
+
### Enumerations
|
367
|
+
|
368
|
+
* [O Auth Provider Error](#o-auth-provider-error)
|
369
|
+
|
370
|
+
#### O Auth Provider Error
|
371
|
+
|
372
|
+
OAuth 2 Authorization error codes
|
373
|
+
|
374
|
+
##### Class Name
|
375
|
+
|
376
|
+
`OAuthProviderErrorEnum`
|
377
|
+
|
378
|
+
##### Fields
|
379
|
+
|
380
|
+
| Name | Description |
|
381
|
+
| --- | --- |
|
382
|
+
| `INVALID_REQUEST` | The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed. |
|
383
|
+
| `INVALID_CLIENT` | Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). |
|
384
|
+
| `INVALID_GRANT` | The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. |
|
385
|
+
| `UNAUTHORIZED_CLIENT` | The authenticated client is not authorized to use this authorization grant type. |
|
386
|
+
| `UNSUPPORTED_GRANT_TYPE` | The authorization grant type is not supported by the authorization server. |
|
387
|
+
| `INVALID_SCOPE` | The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner. |
|
388
|
+
|
389
|
+
### Exceptions
|
390
|
+
|
391
|
+
* [O Auth Provider](#o-auth-provider)
|
392
|
+
|
393
|
+
#### O Auth Provider
|
394
|
+
|
395
|
+
OAuth 2 Authorization endpoint exception.
|
396
|
+
|
397
|
+
##### Class Name
|
398
|
+
|
399
|
+
`OAuthProviderException`
|
400
|
+
|
401
|
+
##### Fields
|
402
|
+
|
403
|
+
| Name | Type | Tags | Description |
|
404
|
+
| --- | --- | --- | --- |
|
405
|
+
| `error` | [`OAuthProviderErrorEnum`](#o-auth-provider-error) | Required | Gets or sets error code. |
|
406
|
+
| `error_description` | `String` | Optional | Gets or sets human-readable text providing additional information on error.<br>Used to assist the client developer in understanding the error that occurred. |
|
407
|
+
| `error_uri` | `String` | Optional | Gets or sets a URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error. |
|
408
|
+
|
409
|
+
##### Example (as JSON)
|
410
|
+
|
411
|
+
```json
|
412
|
+
{
|
413
|
+
"error": "invalid_request",
|
414
|
+
"error_description": null,
|
415
|
+
"error_uri": null
|
416
|
+
}
|
417
|
+
```
|
418
|
+
|
419
|
+
## Utility Classes Documentation
|
420
|
+
|
421
|
+
### ApiHelper Class
|
422
|
+
|
423
|
+
API utility class.
|
424
|
+
|
425
|
+
### Methods
|
426
|
+
|
427
|
+
| Name | Return Type | Description |
|
428
|
+
| --- | --- | --- |
|
429
|
+
| json_deserialize | Hash | Deserializes a JSON string to a Ruby Hash. |
|
430
|
+
| rfc3339 | DateTime | Safely converts a string into an RFC3339 DateTime object. |
|
431
|
+
|
432
|
+
## Common Code Documentation
|
433
|
+
|
434
|
+
### HttpResponse
|
435
|
+
|
436
|
+
Http response received.
|
437
|
+
|
438
|
+
#### Properties
|
439
|
+
|
440
|
+
| Name | Type | Description |
|
441
|
+
| --- | --- | --- |
|
442
|
+
| status_code | Integer | The status code returned by the server. |
|
443
|
+
| reason_phrase | String | The reason phrase returned by the server. |
|
444
|
+
| headers | Hash | Response headers. |
|
445
|
+
| raw_body | String | Response body. |
|
446
|
+
| request | HttpRequest | The request that resulted in this response. |
|
447
|
+
|
448
|
+
### HttpRequest
|
449
|
+
|
450
|
+
Represents a single Http Request.
|
451
|
+
|
452
|
+
#### Properties
|
453
|
+
|
454
|
+
| Name | Type | Tag | Description |
|
455
|
+
| --- | --- | --- | --- |
|
456
|
+
| http_method | HttpMethodEnum | | The HTTP method of the request. |
|
457
|
+
| query_url | String | | The endpoint URL for the API request. |
|
458
|
+
| headers | Hash | Optional | Request headers. |
|
459
|
+
| parameters | Hash | Optional | Request body. |
|
460
|
+
|