# gridscale_api_client_python
This the official Python wrapper for gridscale's [API](https://gridscale.io/en//api-documentation/index.html). Allowing you to manage your own infrastructure from your own applications.
## Prerequisites
First, the Python programming language needs to be installed. This can be done by using the [official downloads](https://www.python.org/downloads/) page.
Once done, download and install via [PyPI](https://pypi.org)
```shell
$ pip3 install gs_api_client
```
## Introduction
First, you will need your [API credentials](https://my.gridscale.io/Easy/APIs/).
In the [examples.py](https://github.com/gridscale/gridscale_api_client_python/blob/develop/examples/examples.py) replace the `AUTH_TOKEN` & `USER_UUID` with your credentials.
## Authentication
These imports and configs need to be setup before other commands can be run. If you do not need synchronous or asynchronous requests, you can leave out `SyncGridscaleApiClient` & `GridscaleApiClient` respectively.
```python
from gs_api_client import Configuration
from gs_api_client import SyncGridscaleApiClient, GridscaleApiClient
# Initiate the configuration
config = Configuration()
config.api_key['X-Auth-Token'] = "AUTH_TOKEN"
config.api_key['X-Auth-UserId'] = "USER_UUID"
# Setup the client
sync_api = SyncGridscaleApiClient(configuration=config)
async_api = GridscaleApiClient(configuration=config)
```
## Async vs. sync client
We provide two clients `SyncGridscaleApiClient` and `GridscaleApiClient`. gridscale's API performs long running operations asynchronously in the background while returning a 202 response code, with the request identifier in the `x-request-id` response header.
The main differences are:
- `GridscaleApiClient` exposes bare gridscale API functionality, while `SyncGridscaleApiClient` adds a convenience layer on top.
- `SyncGridscaleApiClient` determines whether the request is sync or async.
- Makes asynchronous operations behave as if they were synchronous:
- The client will block until the request has finished, successful or not.
- Throws an `AsynchronousApiError` exception, in the case of failure.
- With most `PATCH` and `POST` requests, the synchronous client will return the resulting object instead of an empty body or just the reference.
## Debugging
Adding this line below, will output further information for debugging
```python
config.debug = True
```
## Access response header
Adding `http_info=True` when instantiating the client, return value will be a tuple of response, response code and response headers (dict).
```python
sync_api = SyncGridscaleApiClient(http_info=True)
async_api = GridscaleApiClient(http_info=True)
```
## Basic request examples
```python
from pprint import pprint
# Get all servers
pprint(async_api.get_servers())
# Create a server
pprint(async_api.create_server({'name':'test', 'cores': 1, 'memory': 2}))
# Update a server
pprint(async_api.update_server('<UUID>', {
'name':'windows production Server',
'cores': 2,
'memory': 4
}))
# Delete a server
pprint(client.delete_storage('<UUID>'))
```
## Exhaustive list of all functions
Inside the [examples.py](examples/examples.py) file, you can see some example requests to get your started. All endpoints are fully documented in our [API](https://gridscale.io/en//api-documentation/index.html)
### Requests
- get_request
### Locations
- get_locations
- get_location
### Servers
- get_servers
- get_server
- create_server
- update_server
- delete_server
- get_deleted_servers
- get_server_events
- get_server_metrics
- get_server_power
- update_server_power
- server_power_shutdown
### Server relations
- get_server_linked_ip
- get_server_linked_ips
- get_server_linked_isoimage
- get_server_linked_isoimages
- get_server_linked_network
- get_server_linked_networks
- get_server_linked_storage
- get_server_linked_storages
- link_ip_to_server
- link_isoimage_to_server
- link_network_to_server
- link_storage_to_server
- update_server_linked_isoimage
- update_server_linked_network
- update_server_linked_storage
- unlink_ip_from_server
- unlink_isoimage_from_server
- unlink_network_from_server
- unlink_storage_from_server
### Storages
- get_storages
- get_storage
- create_storage
- delete_storage
- get_deleted_storages
- storage_clone
- storage_rollback
- update_storage
- get_storage_events
### Backups
- get_storage_backups
- delete_storage_backup
- rollback_storage_backup
### Storage Backup Schedule
- get_storage_backup_chedules
- create_storage_backup_schedule
- get_storage_backup_schedule
- delete_storage_backup_schedule
- update_storage_backup_schedule
### Snapshots
- get_snapshots
- get_snapshot
- create_snapshot
- delete_snapshot
- get_snapshot_schedule
- get_snapshot_schedules
- update_snapshot
- create_snapshot_schedule
- update_snapshot_schedule
- delete_snapshot_schedule
- snapshot_export_to_s3
- get_deleted_snapshots
### Templates
- get_templates
- get_template
- create_template
- update_template
- delete_template
- get_template_events
- get_deleted_templates
### Marketplace applications
- get_marketplace_applications
- get_marketplace_application
- create_marketplace_application
- update_marketplace_application
- delete_marketplace_application
- get_marketplace_application_events
### Networks
- get_network
- get_networks
- create_network
- update_network
- delete_network
- get_network_events
- get_deleted_networks
- get_network_pinned_servers()
- update_network_pinned_server()
- delete_network_pinned_server()
### IP addresses
- get_ips
- get_ip
- create_ip
- update_ip
- delete_ip
- get_ip_events
- get_deleted_ips
### Load balancers
- get_loadbalancers
- get_loadbalancer
- create_loadbalancer
- update_loadbalancer
- delete_loadbalancer
- get_loadbalancer_events
- get_deleted_loadbalancers
### PaaS
- get_paas_services
- get_paas_service
- create_paas_service
- update_paas_service
- delete_paas_service
- renew_paas_service_credentials
- get_paas_service_metrics
- get_paas_security_zones
- get_paas_security_zone
- create_paas_security_zone
- update_paas_security_zone
- delete_paas_security_zone
- get_paas_service_templates
- get_deleted_paas_services
### Firewalls
- get_firewalls
- get_firewall
- create_firewall
- update_firewall
- delete_firewall
- get_firewall_events
### ISO images
- get_isoimages
- get_isoimage
- create_isoimage
- update_isoimage
- delete_isoimage
- get_isoimage_events
- get_deleted_isoimages
### Labels
- get_labels
- get_label
### SSH keys
- get_ssh_keys
- get_ssh_key
- create_ssh_key
- update_ssh_key
- delete_ssh_key
- get_ssh_key_events
### Events
- event_get_all
### Object storage
- get_buckets
- get_access_keys
- get_access_key
- create_access_key
- delete_access_key
### Certificates
- get_certificates()
- create_certificate()
- get_certificate()
- delete_certificate()
### Usages
- project_level_usage_get()
- project_level_server_usage_get()
- project_level_distributed_storage_usage_get()
- project_level_rocket_storage_usage_get()
- project_level_storage_backup_usage_get()
- project_level_snapshot_usage_get()
- project_level_template_usage_get()
- project_level_isoimage_usage_get()
- project_level_ip_usage_get()
- project_level_loadbalancer_usage_get()
- project_level_paas_service_usage_get()
- contract_level_usage_get()
- contract_level_server_usage_get()
- contract_level_distributed_storage_usage_get()
- contract_level_rocket_storage_usage_get()
- contract_level_storage_backup_usage_get()
- contract_level_snapshot_usage_get()
- contract_level_template_usage_get()
- contract_level_isoimage_usage_get()
- contract_level_ip_usage_get()
- contract_level_loadbalancer_usage_get()
- contract_level_paas_service_usage_get()
## Development
Create a virtual environment with all necessary dependencies and run the tests as follows:
```shell
$ python -m venv .venv
$ source .venv/bin/activate
$ python -m pip install -r dev-requirements.txt
$ pytest
```
Have fun!
Raw data
{
"_id": null,
"home_page": "https://github.com/gridscale/gridscale_api_client_python",
"name": "gs-api-client",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "API Client",
"author": "Thomas Wiebe",
"author_email": "thomas@gridscale.io",
"download_url": "https://files.pythonhosted.org/packages/bf/02/2d00849ee45b7f5267dcc7b3b04c7aaa80d64458b930d548dc61bf88e4b5/gs_api_client-2.2.1.tar.gz",
"platform": null,
"description": "# gridscale_api_client_python\n\nThis the official Python wrapper for gridscale's [API](https://gridscale.io/en//api-documentation/index.html). Allowing you to manage your own infrastructure from your own applications.\n\n## Prerequisites\n\nFirst, the Python programming language needs to be installed. This can be done by using the [official downloads](https://www.python.org/downloads/) page.\n\nOnce done, download and install via [PyPI](https://pypi.org)\n\n```shell\n$ pip3 install gs_api_client\n```\n\n## Introduction\n\nFirst, you will need your [API credentials](https://my.gridscale.io/Easy/APIs/).\n\nIn the [examples.py](https://github.com/gridscale/gridscale_api_client_python/blob/develop/examples/examples.py) replace the `AUTH_TOKEN` & `USER_UUID` with your credentials.\n\n## Authentication\n\nThese imports and configs need to be setup before other commands can be run. If you do not need synchronous or asynchronous requests, you can leave out `SyncGridscaleApiClient` & `GridscaleApiClient` respectively.\n\n```python\nfrom gs_api_client import Configuration\nfrom gs_api_client import SyncGridscaleApiClient, GridscaleApiClient\n\n# Initiate the configuration\nconfig = Configuration()\nconfig.api_key['X-Auth-Token'] = \"AUTH_TOKEN\"\nconfig.api_key['X-Auth-UserId'] = \"USER_UUID\"\n\n# Setup the client\nsync_api = SyncGridscaleApiClient(configuration=config)\nasync_api = GridscaleApiClient(configuration=config)\n```\n\n## Async vs. sync client\n\nWe provide two clients `SyncGridscaleApiClient` and `GridscaleApiClient`. gridscale's API performs long running operations asynchronously in the background while returning a 202 response code, with the request identifier in the `x-request-id` response header.\n\nThe main differences are:\n\n- `GridscaleApiClient` exposes bare gridscale API functionality, while `SyncGridscaleApiClient` adds a convenience layer on top.\n- `SyncGridscaleApiClient` determines whether the request is sync or async.\n- Makes asynchronous operations behave as if they were synchronous:\n - The client will block until the request has finished, successful or not.\n - Throws an `AsynchronousApiError` exception, in the case of failure.\n- With most `PATCH` and `POST` requests, the synchronous client will return the resulting object instead of an empty body or just the reference.\n\n## Debugging\n\nAdding this line below, will output further information for debugging\n\n```python\nconfig.debug = True\n```\n\n## Access response header\n\nAdding `http_info=True` when instantiating the client, return value will be a tuple of response, response code and response headers (dict).\n\n```python\nsync_api = SyncGridscaleApiClient(http_info=True)\nasync_api = GridscaleApiClient(http_info=True)\n```\n\n## Basic request examples\n\n```python\nfrom pprint import pprint\n\n# Get all servers\npprint(async_api.get_servers())\n\n# Create a server\npprint(async_api.create_server({'name':'test', 'cores': 1, 'memory': 2}))\n\n# Update a server\npprint(async_api.update_server('<UUID>', {\n 'name':'windows production Server',\n 'cores': 2,\n 'memory': 4\n }))\n\n# Delete a server\npprint(client.delete_storage('<UUID>'))\n```\n\n## Exhaustive list of all functions\n\nInside the [examples.py](examples/examples.py) file, you can see some example requests to get your started. All endpoints are fully documented in our [API](https://gridscale.io/en//api-documentation/index.html)\n\n### Requests\n\n- get_request\n\n### Locations\n\n- get_locations\n- get_location\n\n### Servers\n\n- get_servers\n- get_server\n- create_server\n- update_server\n- delete_server\n- get_deleted_servers\n- get_server_events\n- get_server_metrics\n- get_server_power\n- update_server_power\n- server_power_shutdown\n\n### Server relations\n\n- get_server_linked_ip\n- get_server_linked_ips\n- get_server_linked_isoimage\n- get_server_linked_isoimages\n- get_server_linked_network\n- get_server_linked_networks\n- get_server_linked_storage\n- get_server_linked_storages\n- link_ip_to_server\n- link_isoimage_to_server\n- link_network_to_server\n- link_storage_to_server\n- update_server_linked_isoimage\n- update_server_linked_network\n- update_server_linked_storage\n- unlink_ip_from_server\n- unlink_isoimage_from_server\n- unlink_network_from_server\n- unlink_storage_from_server\n\n### Storages\n\n- get_storages\n- get_storage\n- create_storage\n- delete_storage\n- get_deleted_storages\n- storage_clone\n- storage_rollback\n- update_storage\n- get_storage_events\n\n### Backups\n\n- get_storage_backups\n- delete_storage_backup\n- rollback_storage_backup\n\n### Storage Backup Schedule\n\n- get_storage_backup_chedules\n- create_storage_backup_schedule\n- get_storage_backup_schedule\n- delete_storage_backup_schedule\n- update_storage_backup_schedule\n\n### Snapshots\n\n- get_snapshots\n- get_snapshot\n- create_snapshot\n- delete_snapshot\n- get_snapshot_schedule\n- get_snapshot_schedules\n- update_snapshot\n- create_snapshot_schedule\n- update_snapshot_schedule\n- delete_snapshot_schedule\n- snapshot_export_to_s3\n- get_deleted_snapshots\n\n### Templates\n\n- get_templates\n- get_template\n- create_template\n- update_template\n- delete_template\n- get_template_events\n- get_deleted_templates\n\n### Marketplace applications\n\n- get_marketplace_applications\n- get_marketplace_application\n- create_marketplace_application\n- update_marketplace_application\n- delete_marketplace_application\n- get_marketplace_application_events\n\n### Networks\n\n- get_network\n- get_networks\n- create_network\n- update_network\n- delete_network\n- get_network_events\n- get_deleted_networks\n- get_network_pinned_servers()\n- update_network_pinned_server()\n- delete_network_pinned_server()\n\n### IP addresses\n\n- get_ips\n- get_ip\n- create_ip\n- update_ip\n- delete_ip\n- get_ip_events\n- get_deleted_ips\n\n### Load balancers\n\n- get_loadbalancers\n- get_loadbalancer\n- create_loadbalancer\n- update_loadbalancer\n- delete_loadbalancer\n- get_loadbalancer_events\n- get_deleted_loadbalancers\n\n### PaaS\n\n- get_paas_services\n- get_paas_service\n- create_paas_service\n- update_paas_service\n- delete_paas_service\n- renew_paas_service_credentials\n- get_paas_service_metrics\n- get_paas_security_zones\n- get_paas_security_zone\n- create_paas_security_zone\n- update_paas_security_zone\n- delete_paas_security_zone\n- get_paas_service_templates\n- get_deleted_paas_services\n\n### Firewalls\n\n- get_firewalls\n- get_firewall\n- create_firewall\n- update_firewall\n- delete_firewall\n- get_firewall_events\n\n### ISO images\n\n- get_isoimages\n- get_isoimage\n- create_isoimage\n- update_isoimage\n- delete_isoimage\n- get_isoimage_events\n- get_deleted_isoimages\n\n### Labels\n\n- get_labels\n- get_label\n\n### SSH keys\n\n- get_ssh_keys\n- get_ssh_key\n- create_ssh_key\n- update_ssh_key\n- delete_ssh_key\n- get_ssh_key_events\n\n### Events\n\n- event_get_all\n\n### Object storage\n\n- get_buckets\n- get_access_keys\n- get_access_key\n- create_access_key\n- delete_access_key\n\n### Certificates\n\n- get_certificates()\n- create_certificate()\n- get_certificate()\n- delete_certificate()\n\n### Usages\n\n- project_level_usage_get()\n- project_level_server_usage_get()\n- project_level_distributed_storage_usage_get()\n- project_level_rocket_storage_usage_get()\n- project_level_storage_backup_usage_get()\n- project_level_snapshot_usage_get()\n- project_level_template_usage_get()\n- project_level_isoimage_usage_get()\n- project_level_ip_usage_get()\n- project_level_loadbalancer_usage_get()\n- project_level_paas_service_usage_get()\n- contract_level_usage_get()\n- contract_level_server_usage_get()\n- contract_level_distributed_storage_usage_get()\n- contract_level_rocket_storage_usage_get()\n- contract_level_storage_backup_usage_get()\n- contract_level_snapshot_usage_get()\n- contract_level_template_usage_get()\n- contract_level_isoimage_usage_get()\n- contract_level_ip_usage_get()\n- contract_level_loadbalancer_usage_get()\n- contract_level_paas_service_usage_get()\n\n## Development\n\nCreate a virtual environment with all necessary dependencies and run the tests as follows:\n\n```shell\n$ python -m venv .venv\n$ source .venv/bin/activate\n$ python -m pip install -r dev-requirements.txt\n$ pytest\n```\n\nHave fun!\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Official Python idiomatic client for gridscale services",
"version": "2.2.1",
"project_urls": {
"Homepage": "https://github.com/gridscale/gridscale_api_client_python"
},
"split_keywords": [
"api",
"client"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ee0be3877f999decf209634516ba908e6b4c06f2682558f7920552208afe3203",
"md5": "ae3507c8739dad058ea1eafbca5bda43",
"sha256": "c80e224e8e10329b701d670fb08d17a1403131b10eb75da2fd90e0570b6974e3"
},
"downloads": -1,
"filename": "gs_api_client-2.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ae3507c8739dad058ea1eafbca5bda43",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 3005969,
"upload_time": "2023-06-02T08:47:25",
"upload_time_iso_8601": "2023-06-02T08:47:25.312844Z",
"url": "https://files.pythonhosted.org/packages/ee/0b/e3877f999decf209634516ba908e6b4c06f2682558f7920552208afe3203/gs_api_client-2.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bf022d00849ee45b7f5267dcc7b3b04c7aaa80d64458b930d548dc61bf88e4b5",
"md5": "2dc0bfcb044199d0f5965fdce400fa98",
"sha256": "10437e02b5c77a79acdbec79d2e0539c4a4bbda0b7ad82b9c7ae864a38af64e5"
},
"downloads": -1,
"filename": "gs_api_client-2.2.1.tar.gz",
"has_sig": false,
"md5_digest": "2dc0bfcb044199d0f5965fdce400fa98",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 515250,
"upload_time": "2023-06-02T08:47:28",
"upload_time_iso_8601": "2023-06-02T08:47:28.171850Z",
"url": "https://files.pythonhosted.org/packages/bf/02/2d00849ee45b7f5267dcc7b3b04c7aaa80d64458b930d548dc61bf88e4b5/gs_api_client-2.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-02 08:47:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gridscale",
"github_project": "gridscale_api_client_python",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"lcname": "gs-api-client"
}
JSON
