Skip to content

Commit 0407738

Browse files
tsmithjctsmithjc
committed
Merge pull request TheJumpCloud#14 from TheJumpCloud/ts-updates-2018-10-13
API v1 and v2 updates 2018-10-13
2 parents 80cd311 + bb7bf26 commit 0407738

27 files changed

+129
-583
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
# Ruby artifacts
2+
*.gem
3+
14
# input and output directories
25
input
36
output

‎README.md

Lines changed: 99 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -1,167 +1,190 @@
11
## JCAPI-Ruby
22

3-
### Description ###
3+
### Description
44

5-
This repository contains the Ruby client code for the JumpCloud API v1 and v2.
6-
It also provides the tools to generate the client code from the API yaml files, using swagger-codegen.
7-
For detailed instructions on how to generate the code, see the [Contributing](CONTRIBUTING.md) section.
5+
This repository contains the Ruby client code for the JumpCloud API v1 and
6+
v2. It also provides the tools to generate the client code from the API YAML
7+
files, using Swagger Codegen. For detailed instructions on how to generate the
8+
code, see the [Contributing](CONTRIBUTING.md) section.
89

910
### Installing the Ruby Client
1011

11-
#### Installing from github with Bundler
12+
#### Installing from GitHub with Bundler
1213

1314
Add the following line(s) to your Gemfile:
1415

15-
`gem 'jcapiv1', :git => 'https://github.com/TheJumpCloud/jcapi-ruby.git'` for the jcapiv1 gem
16+
`gem 'jcapiv1', :git => 'https://github.com/TheJumpCloud/jcapi-ruby.git'` for the jcapiv1 gem.
1617

17-
`gem 'jcapiv2', :git => 'https://github.com/TheJumpCloud/jcapi-ruby.git'` for the jcapiv2 gem
18+
`gem 'jcapiv2', :git => 'https://github.com/TheJumpCloud/jcapi-ruby.git'` for the jcapiv2 gem.
1819

19-
And run: `bundle install`
20+
And run: `bundle install`.
2021

21-
#### Manual install
22+
#### Manual Install
2223

2324
Change to the appropriate directory (jcapiv1 or jcapiv2) and then run the following
24-
commands to build/install the Ruby Client API package:
25+
commands to build/install the Ruby client API package:
2526

2627
To build the Ruby code into a gem:
28+
2729
```shell
2830
gem build jcapiv1.gemspec
2931
```
32+
3033
Then either install the gem locally:
34+
3135
```shell
3236
gem install --user-install ./jcapiv1-1.0.0.gem
3337
```
38+
3439
Or for all users:
40+
3541
```shell
36-
$ sudo gem install ./jcapiv1-1.0.0.gem
42+
sudo gem install ./jcapiv1-1.0.0.gem
3743
```
3844

3945
### Authentication and Authorization
4046

41-
All endpoints support authentication via API key: see the [Authentication and Authorization](https://docs.jumpcloud.com/2.0/authentication-and-authorization/authentication-and-authorization-overview)
42-
section in our API docs.
43-
44-
Some Systems endpoints (in both API v1 and v2) also support the [System Context authorization](https://docs.jumpcloud.com/2.0/authentication-and-authorization/system-context)
45-
which allows an individual system to manage its information and resource associations.
47+
All endpoints support authentication via API key: see the
48+
[Authentication & Authorization](https://docs.jumpcloud.com/2.0/authentication-and-authorization/authentication-and-authorization-overview)
49+
section in our API documentation.
4650

51+
Some systems endpoints (in both API v1 and v2) also support
52+
[System Context Authorization](https://docs.jumpcloud.com/2.0/authentication-and-authorization/system-context)
53+
which allows an individual system to manage its information and resource
54+
associations.
4755

4856
### Usage Examples
4957

50-
For more detailed instructions, refer to each API's respective README file
51-
([README for API v1](jcapiv1/README.md) and [README for API v2](jcapiv2/README.md))
52-
and the generated docs under each folder.
58+
For more detailed instructions, refer to each API version's respective README
59+
file ([README for API v1](jcapiv1/README.md) and
60+
[README for API v2](jcapiv2/README.md)) and the generated documentation under
61+
each folder.
62+
63+
#### API v1 Example
5364

54-
#### API v1 example:
5565
```ruby
5666
#!/usr/bin/env ruby
5767

58-
# Load the gem
5968
require 'jcapiv1'
6069

61-
# Setup API key:
62-
JCAPIv1.configure do |config|
63-
# Configure API key authorization: x-api-key
64-
config.api_key['x-api-key'] = '<YOUR_JUMPCLOUD_API_KEY>'
65-
end
66-
67-
# instantiate the Systemusers API object:
68-
api_instance = JCAPIv1::SystemusersApi.new
70+
api_key = 'YOUR_API_KEY'
71+
system_user_id = 'YOUR_SYSTEM_USER_ID'
6972

7073
content_type = 'application/json'
7174
accept = 'application/json'
7275

76+
# Set up the configuration object with your API key for authorization.
77+
JCAPIv1.configure do |config|
78+
config.api_key['x-api-key'] = api_key
79+
end
80+
81+
# Instantiate the API object for the group of endpoints you need to use,
82+
# for instance the system users API.
83+
system_users_api = JCAPIv1::SystemusersApi.new
7384

74-
# Example 1: print all users:
85+
# Example 1: Make an API call to retrieve system users.
7586

7687
opts = {
7788
limit: 100, # The number of records to return at once.
78-
sort: 'username' # sort by username
89+
sort: 'username'
7990
}
8091

8192
begin
82-
res = api_instance.systemusers_list(content_type, accept, opts)
83-
puts res.total_count
84-
puts res.results
93+
response = system_users_api.systemusers_list(content_type, accept, opts)
94+
puts response
8595
rescue JCAPIv1::ApiError => e
86-
puts 'Exception when calling SystemusersApi->systemusers_list: #{e}'
96+
puts "Exception when calling SystemusersApi->systemusers_list: #{e}"
8797
end
8898

99+
# Example 2: Make an API call to update a system user.
89100

90-
# Example 2: modify the lastname of a specific user:
91-
92-
# create a put request with the updated last name:
93-
put_request = JCAPIv1::Systemuserputpost.new
94-
put_request.lastname = 'updated last name'
95-
# pass the request in the optional parameters:
96-
opts = {
97-
body: put_request
98-
}
101+
put_request = JCAPIv1::Systemuserput.new
102+
put_request.lastname = 'Updated Last Name'
103+
opts = { body: put_request }
99104

100105
begin
101-
res = api_instance.systemusers_put('<YOUR_USER_ID>', content_type, accept, opts)
102-
puts res
106+
response = system_users_api.systemusers_put(
107+
system_user_id, content_type, accept, opts
108+
)
109+
puts response
103110
rescue JCAPIv1::ApiError => e
104-
puts 'Exception when calling SystemusersApi->systemusers_get: #{e}'
111+
puts "Exception when calling SystemusersApi->systemusers_put: #{e}"
105112
end
106113

107114
```
108115

109116

110-
#### API v2 example:
117+
#### API v2 Example
118+
111119
```ruby
112120
#!/usr/bin/env ruby
113121

114-
# Load the gem
115122
require 'jcapiv2'
116123

117-
# Setup API key:
124+
api_key = 'YOUR_API_KEY'
125+
126+
content_type = 'application/json'
127+
accept = 'application/json'
128+
129+
# Set up the configuration object with your API key for authorization
118130
JCAPIv2.configure do |config|
119-
# Configure API key authorization: x-api-key
120-
config.api_key['x-api-key'] = '<YOUR_JUMPCLOUD_API_KEY>'
131+
config.api_key['x-api-key'] = api_key
121132
end
122133

123-
# instantiate the UserGroups API object:
124-
api_instance = JCAPIv2::UserGroupsApi.new
134+
# Instantiate the API object for the group of endpoints you need to use,
135+
# for instance the user groups API.
136+
user_groups_api = JCAPIv2::UserGroupsApi.new
125137

126-
content_type = 'application/json'
127-
accept = 'application/json'
138+
# Make an API call to retrieve user groups.
128139

129-
# print all user groups:
130140
begin
131-
res = api_instance.groups_user_list(content_type, accept)
132-
puts res
141+
response = user_groups_api.groups_user_list(content_type, accept)
142+
puts response
133143
rescue JCAPIv2::ApiError => e
134-
puts 'Exception when calling UserGroupsApi->groups_user_list: #{e}'
144+
puts "Exception when calling UserGroupsApi->groups_user_list: #{e}"
135145
end
146+
136147
```
137148

138149

139-
#### System Context API example:
150+
#### System Context Authorization Example
151+
140152
```ruby
141153
#!/usr/bin/env ruby
142154

143-
# Load the gem
144155
require 'jcapiv2'
145156

146-
# instantiate the Systems API object:
147-
api_instance = JCAPIv2::SystemsApi.new
157+
# Set headers for System Context Authorization. For detailed instructions on
158+
# how to generate these headers, refer to:
159+
# https://docs.jumpcloud.com/2.0/authentication-and-authorization/system-context
160+
system_id = 'YOUR_SYSTEM_ID'
161+
# The current date on the system, e.g. 'Fri, 16 Jan 1998 12:13:05 GMT'
162+
system_date = 'YOUR_SYSTEM_DATE'
163+
system_signature = 'YOUR_SYSTEM_SIGNATURE'
164+
system_context_auth = \
165+
"Signature keyId=\"system/#{system_id}\","\
166+
'headers="request-line date",'\
167+
'algorithm="rsa-sha256",'\
168+
"signature=\"#{system_signature}\""
148169

149170
content_type = 'application/json'
150171
accept = 'application/json'
151-
system_id = '<YOUR_SYSTEM_ID>'
152-
# set headers for the System Context Authorization:
153-
# for detailed instructions on how to generate these headers,
154-
# refer to: https://docs.jumpcloud.com/2.0/authentication-and-authorization/system-context
155-
opts = {
156-
authorization: 'Signature keyId="system/<YOUR_SYSTEM_ID>",headers="request-line date",algorithm="rsa-sha256",signature="<YOUR_SYSTEM_SIGNATURE>"',
157-
date: 'Thu, 19 Oct 2017 17:27:57 GMT' # the current date on the system
158-
}
172+
173+
# Instantiate the API object for the group of endpoints you need to use,
174+
# for instance the user groups API.
175+
systems_api = JCAPIv2::SystemsApi.new
176+
177+
# Make an API call to retrieve all system groups this system is a member of.
178+
179+
opts = { authorization: system_context_auth, date: system_date }
159180

160181
begin
161-
# list the system groups this system is a member of:
162-
res = api_instance.graph_system_member_of(system_id, content_type, accept, opts)
163-
puts res
182+
response = systems_api.graph_system_member_of(
183+
system_id, content_type, accept, opts
184+
)
185+
puts response
164186
rescue JCAPIv2::ApiError => e
165-
puts 'Exception when calling systemsAPI->graph_system_member_of: #{e}'
187+
puts "Exception when calling systemsAPI->graph_system_member_of: #{e}"
166188
end
189+
167190
```

‎config_v1.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
22
"gemName": "jcapiv1",
33
"moduleName": "JCAPIv1",
4-
"gemVersion": "1.1.0"
4+
"gemVersion": "1.2.0"
55
}

‎config_v2.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
22
"gemName": "jcapiv2",
33
"moduleName": "JCAPIv2",
4-
"gemVersion": "1.1.0"
4+
"gemVersion": "1.2.0"
55
}

‎jcapiv1/README.md

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ JCAPIv1 - the Ruby gem for the JumpCloud APIs
77
This SDK is automatically generated by the [Swagger Codegen](https://github.com/swagger-api/swagger-codegen) project:
88

99
- API version: 1.0
10-
- Package version: 1.1.0
10+
- Package version: 1.2.0
1111
- Build package: io.swagger.codegen.languages.RubyClientCodegen
1212

1313
## Installation
@@ -23,15 +23,15 @@ gem build jcapiv1.gemspec
2323
Then either install the gem locally:
2424

2525
```shell
26-
gem install ./jcapiv1-1.1.0.gem
26+
gem install ./jcapiv1-1.2.0.gem
2727
```
28-
(for development, run `gem install --dev ./jcapiv1-1.1.0.gem` to install the development dependencies)
28+
(for development, run `gem install --dev ./jcapiv1-1.2.0.gem` to install the development dependencies)
2929

3030
or publish the gem to a gem hosting service, e.g. [RubyGems](https://rubygems.org/).
3131

3232
Finally add this to the Gemfile:
3333

34-
gem 'jcapiv1', '~> 1.1.0'
34+
gem 'jcapiv1', '~> 1.2.0'
3535

3636
### Install from Git
3737

@@ -172,7 +172,6 @@ Class | Method | HTTP request | Description
172172
- [JCAPIv1::SystemputAgentBoundMessages](docs/SystemputAgentBoundMessages.md)
173173
- [JCAPIv1::Systemslist](docs/Systemslist.md)
174174
- [JCAPIv1::Systemuser](docs/Systemuser.md)
175-
- [JCAPIv1::SystemuserAttributes](docs/SystemuserAttributes.md)
176175
- [JCAPIv1::Systemuserbinding](docs/Systemuserbinding.md)
177176
- [JCAPIv1::Systemuserbindingsput](docs/Systemuserbindingsput.md)
178177
- [JCAPIv1::Systemuserput](docs/Systemuserput.md)

‎jcapiv1/docs/Command.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Name | Type | Description | Notes
66
**name** | **String** | | [optional]
77
**command** | **String** | The command to execute on the server. |
88
**command_type** | **String** | The Command OS | [optional]
9-
**command_runners** | **Array&lt;String&gt;** | an array of IDs of the Command Runner Users that can execute this command. | [optional]
9+
**command_runners** | **Array&lt;String&gt;** | An array of IDs of the Command Runner Users that can execute this command. | [optional]
1010
**user** | **String** | The ID of the system user to run the command as. |
1111
**sudo** | **BOOLEAN** | | [optional]
1212
**systems** | **Array&lt;String&gt;** | An array of system IDs to run the command on. Not available if you are using Groups. | [optional]

‎jcapiv1/docs/CommandslistResults.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Name | Type | Description | Notes
99
**launch_type** | **String** | How the Command is executed. | [optional]
1010
**listens_to** | **String** | | [optional]
1111
**schedule** | **String** | A crontab that consists of: [ (seconds) (minutes) (hours) (days of month) (months) (weekdays) ] or [ immediate ]. If you send this as an empty string, it will run immediately. | [optional]
12-
**trigger** | **String** | trigger to execute command. | [optional]
12+
**trigger** | **String** | Trigger to execute command. | [optional]
1313
**schedule_repeat_type** | **String** | When the command will repeat. | [optional]
1414
**organization** | **String** | The ID of the Organization. | [optional]
1515
**_id** | **String** | The ID of the command. | [optional]

‎jcapiv1/docs/OrganizationslistResults.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
## Properties
44
Name | Type | Description | Notes
55
------------ | ------------- | ------------- | -------------
6-
**_id** | **String** | the ID of the organization. | [optional]
6+
**_id** | **String** | The ID of the organization. | [optional]
77
**display_name** | **String** | The name of the organization. | [optional]
88
**logo_url** | **String** | The organization logo image URL. | [optional]
99

‎jcapiv1/docs/Systemuser.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ Name | Type | Description | Notes
2727
**associated_tag_count** | **Integer** | | [optional]
2828
**totp_enabled** | **BOOLEAN** | | [optional]
2929
**password_expiration_date** | **String** | | [optional]
30-
**attributes** | [**Array&lt;SystemuserAttributes&gt;**](SystemuserAttributes.md) | | [optional]
30+
**attributes** | **Array&lt;Object&gt;** | | [optional]
3131
**created** | **String** | | [optional]
3232
**samba_service_user** | **BOOLEAN** | | [optional]
3333
**password_never_expires** | **BOOLEAN** | | [optional]

‎jcapiv1/docs/SystemuserAttributes.md

Lines changed: 0 additions & 8 deletions
This file was deleted.

0 commit comments

Comments
 (0)