1# gridscale_api_client_python 2 3This 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. 4 5## Prerequisites 6 7First, the Python programming language needs to be installed. This can be done by using the [official downloads](https://www.python.org/downloads/) page. 8 9Once done, download and install via [PyPI](https://pypi.org) 10 11```shell 12$ pip3 install gs_api_client 13``` 14 15## Introduction 16 17First, you will need your [API credentials](https://my.gridscale.io/Easy/APIs/). 18 19In the [examples.py](examples/examples.py) replace the `AUTH_TOKEN` & `USER_UUID` with your credentials. 20 21## Authentication 22 23These 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. 24 25```python 26from gs_api_client import Configuration 27from gs_api_client import SyncGridscaleApiClient, GridscaleApiClient 28 29# Initiate the configuration 30config = Configuration() 31config.api_key['X-Auth-Token'] = "AUTH_TOKEN" 32config.api_key['X-Auth-UserId'] = "USER_UUID" 33 34# Setup the client 35sync_api = SyncGridscaleApiClient(configuration=config) 36async_api = GridscaleApiClient(configuration=config) 37``` 38 39## Async vs. sync client 40 41We 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. 42 43The main differences are: 44 45- `GridscaleApiClient` exposes bare gridscale API functionality, while `SyncGridscaleApiClient` adds a convenience layer on top. 46- `SyncGridscaleApiClient` determines whether the request is sync or async. 47- Makes asynchronous operations behave as if they were synchronous: 48 - The client will block until the request has finished, successful or not. 49 - Throws an `AsynchronousApiError` exception, in the case of failure. 50- With most `PATCH` and `POST` requests, the synchronous client will return the resulting object instead of an empty body or just the reference. 51 52## Debugging 53 54Adding this line below, will output further information for debugging 55 56```python 57config.debug = True 58``` 59 60## Access response header 61 62Adding `http_info=True` when instantiating the client, return value will be a tuple of response, response code and response headers (dict). 63 64```python 65sync_api = SyncGridscaleApiClient(http_info=True) 66async_api = GridscaleApiClient(http_info=True) 67``` 68 69## Basic request examples 70 71```python 72from pprint import pprint 73 74# Get all servers 75pprint(async_api.get_servers()) 76 77# Create a server 78pprint(async_api.create_server({'name':'test', 'cores': 1, 'memory': 2})) 79 80# Update a server 81pprint(async_api.update_server('<UUID>', { 82 'name':'windows production Server', 83 'cores': 2, 84 'memory': 4 85 })) 86 87# Delete a server 88pprint(client.delete_storage('<UUID>')) 89``` 90 91## Exhaustive list of all functions 92 93Inside 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) 94 95### Requests 96 97- get_request 98 99### Locations 100 101- get_locations 102- get_location 103- get_location_ips 104- get_location_isoimages 105- get_location_networks 106- get_location_servers 107- get_location_snapshots 108- get_location_storages 109- get_location_templates 110 111### Servers 112 113- get_servers 114- get_server 115- create_server 116- update_server 117- delete_server 118- get_deleted_servers 119- get_server_events 120- get_server_metrics 121- get_server_power 122- update_server_power 123- server_power_shutdown 124 125### Server relations 126 127- get_server_linked_ip 128- get_server_linked_ips 129- get_server_linked_isoimage 130- get_server_linked_isoimages 131- get_server_linked_network 132- get_server_linked_networks 133- get_server_linked_storage 134- get_server_linked_storages 135- link_ip_to_server 136- link_isoimage_to_server 137- link_network_to_server 138- link_storage_to_server 139- update_server_linked_isoimage 140- update_server_linked_network 141- update_server_linked_storage 142- unlink_ip_from_server 143- unlink_isoimage_from_server 144- unlink_network_from_server 145- unlink_storage_from_server 146 147### Storages 148 149- get_storages 150- get_storage 151- create_storage 152- delete_storage 153- get_deleted_storages 154- storage_clone 155- storage_rollback 156- update_storage 157- get_storage_events 158 159### Backups 160 161- get_storage_backups 162- delete_storage_backup 163- rollback_storage_backup 164 165### Storage Backup Schedule 166 167- get_storage_backup_chedules 168- create_storage_backup_schedule 169- get_storage_backup_schedule 170- delete_storage_backup_schedule 171- update_storage_backup_schedule 172 173### Snapshots 174 175- get_snapshots 176- get_snapshot 177- create_snapshot 178- delete_snapshot 179- get_snapshot_schedule 180- get_snapshot_schedules 181- update_snapshot 182- create_snapshot_schedule 183- update_snapshot_schedule 184- delete_snapshot_schedule 185- snapshot_export_to_s3 186- get_deleted_snapshots 187 188### Templates 189 190- get_templates 191- get_template 192- create_template 193- update_template 194- delete_template 195- get_template_events 196- get_deleted_templates 197 198### Marketplace applications 199 200- get_marketplace_applications 201- get_marketplace_application 202- create_marketplace_application 203- update_marketplace_application 204- delete_marketplace_application 205- get_marketplace_application_events 206 207### Networks 208 209- get_network 210- get_networks 211- create_network 212- update_network 213- delete_network 214- get_network_events 215- get_deleted_networks 216 217### IP addresses 218 219- get_ips 220- get_ip 221- create_ip 222- update_ip 223- delete_ip 224- get_ip_events 225- get_deleted_ips 226 227### Load balancers 228 229- get_loadbalancers 230- get_loadbalancer 231- create_loadbalancer 232- update_loadbalancer 233- delete_loadbalancer 234- get_loadbalancer_events 235- get_deleted_loadbalancers 236 237### PaaS 238 239- get_paas_services 240- get_paas_service 241- create_paas_service 242- update_paas_service 243- delete_paas_service 244- renew_paas_service_credentials 245- get_paas_service_metrics 246- get_paas_security_zones 247- get_paas_security_zone 248- create_paas_security_zone 249- update_paas_security_zone 250- delete_paas_security_zone 251- get_paas_service_templates 252- get_deleted_paas_services 253 254### Firewalls 255 256- get_firewalls 257- get_firewall 258- create_firewall 259- update_firewall 260- delete_firewall 261- get_firewall_events 262 263### ISO images 264 265- get_isoimages 266- get_isoimage 267- create_isoimage 268- update_isoimage 269- delete_isoimage 270- get_isoimage_events 271- get_deleted_isoimages 272 273### Labels 274 275- get_labels 276- get_label 277 278### SSH keys 279 280- get_ssh_keys 281- get_ssh_key 282- create_ssh_key 283- update_ssh_key 284- delete_ssh_key 285- get_ssh_key_events 286 287### Events 288 289- event_get_all 290 291### Object storage 292 293- get_buckets 294- get_access_keys 295- get_access_key 296- create_access_key 297- delete_access_key 298 299## Development 300 301Create a virtual environment with all necessary dependencies and run the tests as follows: 302 303```shell 304$ python -m venv .venv 305$ source .venv/bin/activate 306$ python -m pip install -r dev-requirements.txt 307$ pytest 308``` 309 310Have fun! 311