Skip to content

Commit

Permalink
Update readme and code examples
Browse files Browse the repository at this point in the history
  • Loading branch information
@tsmithjc
tsmithjc committed Oct 13, 2018
1 parent 6f4c976 commit f296872
Showing 1 changed file with 134 additions and 72 deletions.
206 changes: 134 additions & 72 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,121 +2,183 @@

### Description

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

### Installing the Python Client

You can run the following pip commands in order to install the packages directly from Github:
You can run the following `pip` commands in order to install the packages
directly from GitHub:

```
pip install git+https://github.com/TheJumpCloud/jcapi-python.git#subdirectory=jcapiv1
pip install git+https://github.com/TheJumpCloud/jcapi-python.git#subdirectory=jcapiv2
```

Alternatively you can also pull this repository and install manually:
Change to the appropriate directory (jcapiv1 or jcapiv2) and then run the following command:
Alternatively you can also pull this repository and install manually. Change to
the appropriate directory (jcapiv1 or jcapiv2) and then run one of the
following commands.

To install the package for the local user:

```
$ python setup.py install --user
```

To install the package for all users:

```
$ sudo python setup.py install
```

### Authentication and Authorization

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) section in our API docs.
All endpoints support authentication via API key: see the
[Authentication & Authorization](https://docs.jumpcloud.com/2.0/authentication-and-authorization/authentication-and-authorization-overview)
section in our API documentation.

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) which allows an individual system to manage its information and resource associations.
Some systems endpoints (in both API v1 and v2) also support
[System Context Authorization](https://docs.jumpcloud.com/2.0/authentication-and-authorization/system-context)
which allows an individual system to manage its information and resource
associations.

### Usage Examples

For more detailed instructions, refer to each API's respective README file ([README for API v1](jcapiv1/README.md) and [README for API v2](jcapiv2/README.md)) and the generated docs under each folder.
For more detailed instructions, refer to each API version's respective README
file ([README for API v1](jcapiv1/README.md) and
[README for API v2](jcapiv2/README.md)) and the generated documentation under
each folder.

#### API v1 Example

#### API v1 example:
```python
"""JumpCloud API v1 example."""

import jcapiv1
from jcapiv1.rest import ApiException

...
content_type = 'application/json'
accept = 'application/json'

# set up the configuration object with your API key for authorization:
jcapiv1.configuration.api_key['x-api-key'] = '<YOUR_API_KEY>'

# instantiate the API object for the group of endpoints you need to use
# for instance for Systemusers API:
systemusersAPI = jcapiv1.SystemusersApi()

try:
# make an API call to retrieve all systemusers:
users = systemusersAPI.systemusers_list(content_type, accept)
print(users)
except ApiException as e:
print("Exception when calling SystemusersApi->systemusers_list: %s\n" % e)

try:
# make an API call to modify a specific user's last name:
put_request = jcapiv1.Systemuserputpost()
put_request.lastname = 'Updated Last Name'
systemusersAPI.systemusers_put('<YOUR_SYSTEMUSER_ID>', content_type, accept, body=put_request)
except ApiException as e:
print("Exception when calling SystemusersApi->systemusers_put: %s\n" % e)
API_KEY = "YOUR_API_KEY"
SYSTEM_USER_ID = "YOUR_SYSTEM_USER_ID"
SYSTEM_USER_EMAIL = "YOUR_SYSTEM_USER_EMAIL"
SYSTEM_USER_USERNAME = "YOUR_SYSTEM_USER_USERNAME"

CONTENT_TYPE = "application/json"
ACCEPT = "application/json"

# Set up the configuration object with your API key for authorization
CONFIGURATION = jcapiv1.Configuration()
CONFIGURATION.api_key['x-api-key'] = API_KEY

# Instantiate the API object for the group of endpoints you need to use,
# for instance the system users API
API_INSTANCE = jcapiv1.SystemusersApi(jcapiv1.ApiClient(CONFIGURATION))

def list_users():
"""Make an API call to retrieve all system users."""
try:
users = API_INSTANCE.systemusers_list(CONTENT_TYPE, ACCEPT)
print(users)
except ApiException as err:
print("Exception when calling SystemusersApi->systemusers_list: %s\n" % err)

def update_user():
"""Make an API call to update a system user."""
put_request = jcapiv1.Systemuserputpost(email=SYSTEM_USER_EMAIL, username=SYSTEM_USER_USERNAME)
put_request.lastname = "Updated Last Name"

try:
user = API_INSTANCE.systemusers_put(SYSTEM_USER_ID, CONTENT_TYPE, ACCEPT, body=put_request)
print(user)
except ApiException as err:
print("Exception when calling SystemusersApi->systemusers_put: %s\n" % err)

if __name__ == "__main__":
list_users()
update_user()

```

#### API v2 example:
#### API v2 Example

```python
"""JumpCloud API v2 example."""

import jcapiv2
from jcapiv2.rest import ApiException

...
content_type = 'application/json'
accept = 'application/json'
API_KEY = "YOUR_API_KEY"

CONTENT_TYPE = "application/json"
ACCEPT = "application/json"

# Set up the configuration object with your API key for authorization
CONFIGURATION = jcapiv2.Configuration()
CONFIGURATION.api_key['x-api-key'] = API_KEY

# set up the configuration object with your API key:
jcapiv2.configuration.api_key['x-api-key'] = '<YOUR_API_KEY>'
# Instantiate the API object for the group of endpoints you need to use,
# for instance the user groups API
API_INSTANCE = jcapiv2.UserGroupsApi(jcapiv2.ApiClient(CONFIGURATION))

# instantiate the API object for the group of endpoints you need to use
# for instance for User Groups API:
userGroupsAPI = jcapiv2.UserGroupsApi()
def get_user_groups():
"""Make an API call to retrieve all user groups."""
try:
user_groups = API_INSTANCE.groups_user_list(CONTENT_TYPE, ACCEPT)
print(user_groups)
except ApiException as err:
print("Exception when calling UserGroupsApi->groups_user_list: %s\n" % err)

try:
# make an API call to retrieve all user groups:
userGroups = userGroupsAPI.groups_user_list(content_type, accept)
print(userGroups)
except ApiException as e:
print("Exception when calling UserGroupsApi->groups_user_list: %s\n" % e)
if __name__ == "__main__":
get_user_groups()

```

#### System Context Authorization example:
#### System Context Authorization Example

```python
"""JumpCloud system context authorization example."""

import jcapiv2
from jcapiv2.rest import ApiException

content_type = 'application/json'
accept = 'application/json'
system_id = '<YOUR_SYSTEM_ID>'

# set headers for the System Context Authorization:
# for detailed instructions on how to generate these headers,
# refer to: https://docs.jumpcloud.com/2.0/authentication-and-authorization/system-context
sys_context_auth = 'Signature keyId="system/<YOUR_SYSTEM_ID>",headers="request-line date",algorithm="rsa-sha256",signature="<YOUR_SYSTEM_SIGNATURE>"'
sys_context_date = 'Thu, 19 Oct 2017 17:27:57 GMT' # the current date on the system

# instantiate the API object for the group of endpoints you need to use
# for instance for User Groups API:
systemsAPI = jcapiv2.SystemsApi()

try:
# list the system groups this system is a member of:
# Note that we pass the System Context Authorization headers as the 'date' and 'authorization' parameters
groups = systemsAPI.graph_system_member_of(system_id, content_type, accept, date=sys_context_date, authorization=sys_context_auth)
print groups
except ApiException as e:
print("Exception when calling systemsAPI->graph_system_member_of: %s\n" % e)
# Set headers for System Context Authorization. For detailed instructions on
# how to generate these headers, refer to:
# https://docs.jumpcloud.com/2.0/authentication-and-authorization/system-context
SYSTEM_ID = "YOUR_SYSTEM_ID"
# The current date on the system, e.g. "Thu, 09 Aug 1990 14:25:15 GMT"
SYSTEM_DATE = "YOUR_SYSTEM_DATE"
SYSTEM_SIGNATURE = "YOUR_SYSTEM_SIGNATURE"
SYSTEM_CONTEXT_AUTH = (
'Signature keyId="system/{}",'
'headers="request-line date",'
'algorithm="rsa-sha256",'
'signature="{}"'
).format(SYSTEM_ID, SYSTEM_SIGNATURE)

CONTENT_TYPE = "application/json"
ACCEPT = "application/json"

# Set up the configuration object
CONFIGURATION = jcapiv2.Configuration()

# Instantiate the API object for the group of endpoints you need to use,
# for instance the systems API
API_INSTANCE = jcapiv2.SystemsApi(jcapiv2.ApiClient(CONFIGURATION))

def get_system_groups():
"""Make an API call to retrieve all system groups this system is a member of."""
try:
# Note the System Context Authorization headers are passed as arguments
system_groups = API_INSTANCE.graph_system_member_of(
SYSTEM_ID, CONTENT_TYPE, ACCEPT,
date=SYSTEM_DATE, authorization=SYSTEM_CONTEXT_AUTH,
)
print(system_groups)
except ApiException as err:
print("Exception when calling systemsAPI->graph_system_member_of: %s\n" % err)

if __name__ == "__main__":
get_system_groups()

```

0 comments on commit f296872

Please sign in to comment.