User Tools

Site Tools


manuals:vps:api

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
Next revisionBoth sides next revision
manuals:vps:api [2017/02/12 15:26] – API v4.0 Aithermanuals:vps:api [2024/01/02 20:44] – Update auth methods aither
Line 1: Line 1:
 ====== API ====== ====== API ======
  
-Our API is running at https://api.vpsfree.cz. The API can be used to perform most +Our API is running at https://api.vpsfree.cz. The API can be used to perform 
-actions, just like you can do from the web interface. The only things that the API currently doesn’t include +any action that you can do in the web interface. In fact, the web interface 
-are the management of user profiles (address, email, etc.) and data transfers. +running at https://vpsadmin.vpsfree.cz uses the API and calls it for every 
- +action.
-In reality, the web interface running at https://vpsadmin.vpsfree.cz uses +
-the API and calls it for every action.+
  
 ===== API Documentation ===== ===== API Documentation =====
 The API documentation, i.e. a list of objects, possible actions as well as input and output The API documentation, i.e. a list of objects, possible actions as well as input and output
-parameters can be found at https://api.vpsfree.cz/v4.0/.+parameters can be found at https://api.vpsfree.cz/v6.0/.
  
 Even without logging in, you can see a list of all objects, i.e. even those that only Even without logging in, you can see a list of all objects, i.e. even those that only
Line 25: Line 23:
  
   * Ruby - https://github.com/vpsfreecz/vpsfree-client   * Ruby - https://github.com/vpsfreecz/vpsfree-client
-  * PHP - https://github.com/vpsfreecz/haveapi-client-php +  * PHP - https://github.com/vpsfreecz/haveapi/tree/master/clients/php 
-  * JavaScript - https://github.com/vpsfreecz/haveapi-client-js +  * JavaScript - https://github.com/vpsfreecz/haveapi/tree/master/clients/js 
-  * The HaveAPI web interface - https://github.com/vpsfreecz/haveapi-webui +  * Go - https://github.com/vpsfreecz/haveapi/tree/master/clients/go 
-  * A file system based on FUSE - https://github.com/vpsfreecz/haveapi-fs+  * The HaveAPI web interface - https://github.com/vpsfreecz/haveapi-webui (outdated) 
 +  * A file system based on FUSE - https://github.com/vpsfreecz/haveapi-fs (outdated)
  
 Usage examples can always be found in the ''README.md'' of each client. In general, the client Usage examples can always be found in the ''README.md'' of each client. In general, the client
Line 39: Line 38:
  
 ===== Authentication===== ===== Authentication=====
-There are two authentication methods available. The first and simpler one is HTTP +There are two authentication methods:
-basic. The name and password must be sent along with every API request. This is a good +
-choice for one-off actions. However, if you need to call the API several times or +
-automatically, storing the password on the disk or copying it constantly is not a good idea.+
  
-Another method is authentication using tokens. The way this method works is that the client first +  * [[#http_basic|HTTP Basic]] 
-requests a token to be created, one for which the client needs the name and password. As soon as the client receives +  * [[#tokens|Using tokens]] 
-the token, the name and password can be forgotten since it is the token that is then used for further authentication.+ 
 +Example usage in different programming languages can be found in [[https://api.vpsfree.cz/v6.0/#auth|API documentation]]. 
 + 
 +==== HTTP Basic ==== 
 + The name and password must be sent along with every API request in HTTP header //Authorization//
 +This is a good choice for one-off actions. However, if you need to call the API repeatedly or 
 +automatically, storing the password on the disk or entering it constantly is not a good idea. 
 +HTTP Basic cannot be used if two-factor authentication is enabled on your account. 
 + 
 +==== Tokens ==== 
 +The client first requests a token using your credentials and optionally also TOTP. 
 +As soon as the client receives the token, the credentials can be forgotten and the token 
 +is used for authentication.
  
 There can be several types of tokens with different lifetimes: There can be several types of tokens with different lifetimes:
  
-  * fixed - token validity is fixed +  * //fixed// - token validity is fixed 
-  * renewable_manual - token validity can be manually extended +  * //renewable_manual// - token validity can be manually extended 
-  * renewable_auto - token validity is extended after every request +  * //renewable_auto// - token validity is extended after every request 
-  * permament - the token is valid permanently, or until it is deleted+  * //permament// - the token is valid permanently, or until it is deleted
  
-The type of token and time period by which its validity is extended is chosen by the client.+The type of token and time period by which its validity is extended is chosen 
 +by the client.
  
 ===== CLI ===== ===== CLI =====
Line 165: Line 174:
  
 Commands: Commands:
-vps remote_console VPS_ID            Open VPS remote console+action_state wait <STATE ID>         Block until the action is finished  
 +vps remote_console VPS_ID            Open VPS remote console                        
 +vps migrate_many VPS_ID...           Migrate multiple VPSes using a migration plan                                                                                                           
 +snapshot download [SNAPSHOT_ID]      Download a snapshot as an archive or a stream 
 +snapshot send SNAPSHOT_ID            Download a snapshot stream and write it on stdout 
 +backup dataset [DATASET_ID] FILESYSTEM Backup dataset locally 
 +backup vps [VPS_ID] FILESYSTEM       Backup VPS locally 
 +ip_traffic top                       Live IP traffic monitor
  
 Available resources: Available resources:
-auth_token 
 cluster cluster
 cluster_resource cluster_resource
 +cluster_resource_package
 +cluster_resource_package.item
 dataset dataset
 dataset.snapshot dataset.snapshot
 dataset.plan dataset.plan
 +dataset.property_history
 dataset_plan dataset_plan
 dns_resolver dns_resolver
Line 179: Line 197:
 environment.config_chain environment.config_chain
 environment.dataset_plan environment.dataset_plan
 +host_ip_address
 integrity_check integrity_check
 integrity_fact integrity_fact
 integrity_object integrity_object
 ip_address ip_address
 +ip_traffic
 +ip_traffic_monitor
 +language
 location location
 mail_log mail_log
Line 188: Line 210:
 mail_template mail_template
 mail_template.recipient mail_template.recipient
 +mail_template.translation
 +migration_plan
 +migration_plan.vps_migration
 +network
 +network_interface
 node node
 +node.status
 +object_history
 os_template os_template
 pool pool
 +session_token
 snapshot_download snapshot_download
 +system_config
 +transaction
 transaction_chain transaction_chain
-transaction_chain.transaction 
 user user
 user.environment_config user.environment_config
 user.cluster_resource user.cluster_resource
 +user.public_key
 +user.mail_role_recipient
 +user.mail_template_recipient
 user.state_log user.state_log
 +user_cluster_resource_package
 +user_cluster_resource_package.item
 +user_namespace
 +user_namespace_map
 +user_namespace_map.entry
 user_session user_session
 vps vps
Line 203: Line 242:
 vps.config vps.config
 vps.feature vps.feature
-vps.ip_address 
 vps.mount vps.mount
 +vps.outage_window
 vps.console_token vps.console_token
 +vps.status
 vps_config vps_config
 +monitored_event
 +monitored_event.log
 +outage
 +outage.entity
 +outage.handler
 +outage_update
 +user_outage
 +vps_outage
 +vps_outage_mount
 +help_box
 +news_log
 +incoming_payment
 +payment_stats
 +user_account
 +user_payment
 +user_request
 +user_request.registration
 +user_request.change
 +action_state
 </code> </code>
  
Line 234: Line 293:
     -a, --auth METHOD                Authentication method     -a, --auth METHOD                Authentication method
     -s, --save                       Save credentials to config file for later     -s, --save                       Save credentials to config file for later
-        --username USER              User name+        --user USER                  User name
         --password PASSWORD          Password         --password PASSWORD          Password
         --token TOKEN                Token         --token TOKEN                Token
Line 546: Line 605:
 require 'vpsfree/client' require 'vpsfree/client'
  
-api = VpsFree::Client::Client.new+api = VpsFree::Client.new
 api.authenticate(:token, token: 'PUT YOUR TOKEN HERE') api.authenticate(:token, token: 'PUT YOUR TOKEN HERE')
  
Line 577: Line 636:
 require 'vpsfree/client' require 'vpsfree/client'
  
-api = VpsFree::Client::Client.new+api = VpsFree::Client.new
 api.authenticate(:token, token: 'PUT YOUR TOKEN HERE') api.authenticate(:token, token: 'PUT YOUR TOKEN HERE')
  
manuals/vps/api.txt · Last modified: 2024/01/02 21:05 by aither