Knowledge base

Information about vpsFree.org, manuals and FAQs.

User Tools

Site Tools

You are here: Knowledge Base of vpsFree.org » manuals » vps » API
Trace:
manuals:vps:api

Differences

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

Link to this comparison view

Next revision		Previous revision
manuals:vps:api [2016/12/11 14:44] – created tomsmanuals:vps:api [2025/03/24 20:40] (current) – Fix API doc link 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/v3.0/.+parameters can be found at https://api.vpsfree.cz/.
  
 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.+
  
-There can be several types of tokens with different lifetimes:+Example usage in different programming languages can be found in [[https://api.vpsfree.cz/v6.0/#auth|API documentation]].
  
-  * fixed - token validity is fixed +==== HTTP Basic ==== 
-  * renewable_manual - token validity can be manually extended + The name and password must be sent along with every API request in HTTP header //Authorization//. 
-  * renewable_auto - token validity is extended after every request +This is a good choice for one-off actions. However, if you need to call the API repeatedly or 
-  * permament - the token is valid permanently, or until it is deleted+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.
  
-The type of token and time period by which its validity is extended is chosen by the client.+==== 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.
  
-===== CLI ===== +There can be several types of tokens with different lifetimes:
-[[https://github.com/vpsfreecz/vpsfree-client|The Ruby client]] also includes a CLI. +
-In order for it to work properly, you need Ruby >= 2.0 and Ruby header files, +
-OpenSSL and ncurses (mostly packages with the ''-dev'' or ''-devel'' suffix)+
  
-<note> +  * //fixed// - token validity is fixed 
-If you’re using OS X, you first need to install OpenSSL using [[http://brew.sh/|Homebrew]] and only then +  * //renewable_manual// - token validity can be manually extended 
-can you install EventMachine (a gem required by the client).+  * //renewable_auto// - token validity is extended after every request 
 +  * //permament// - the token is valid permanently, or until it is deleted
  
-<code> +The type of token and time period by which its validity is extended is chosen 
-$ brew install openssl +by the client.
-$ sudo gem install eventmachine -- --with-opt-include="/usr/local/opt/openssl/" +
-</code> +
-</note>+
  
-It can be installed using ruby gems:+===== Scopes ===== 
 +Authentication tokens can be restricted to selected actions. Each action has its own scope, 
 +you can find the available scopes in the documentation. You can configure scopes when you're 
 +requesting a new authentication token.
  
-<code> +Example scopes:
-$ gem install vpsfree-client +
-</code>+
  
-==== Installing in Windows 10 Using a Ubuntu Linux Subsystem ====+  * ''all'' allow access to all actions, this is used by the web interface and it is the default scope 
 +  *  an empty scope will allow access only to ''user#current'', which gives information about the current user; this is used for logins from Discourse and KB 
 +  * ''vps#show'' allow access to action show on vps resource 
 +  * ''vps#show:vps_id=123'' allow access to action show on a specific VPS 
 +  * ''vps#*'' allow all actions on vps resource 
 +  * ''vps#*:vps_id=123'' all actions on vps resource, but only with VPS ID 123 
 +  * ''{vps,dataset}#{index,show}'' list and show info about VPS and datasets
  
-=== Installing Ubuntu (Windows 10 Subsystem for Linux) ===+Scopes can contain globs for resource and action names. Action name is separated from resource name by a hash (''#''). Optional object IDs are separated from action name by a colon ('':'') and cannot contain globs. You can find a list of available scopes and their parameters in the [[https://api.vpsfree.cz/|documentation]]. Each token can have multiple scopes separated by spaces. At least one scope must match the called action in order for access to be granted.
  
-  - in Windows 10, enable Developer Mode, let it install +===== Installing vpsfree-client ===== 
-  - in the Programs and Features menu, open Turn Windows Features On or Off, scroll to the very bottom, choose Windows Subsystem for Linux, run the installation and let the computer restart +[[https://github.com/vpsfreecz/vpsfree-client|The Ruby client]] also includes a CLI. 
-  - after the restart, run bash in the Start menu as admin +In order for it to work properly, you need Ruby >= 2.7, Ruby header files and ncurses (mostly packages with the ''-dev'' or ''-devel'' suffix).
-  - create a Unix username and password +
-  - press the Y key and let the Ubuntu base be installed +
- +
-=== Installing Dependencies ===+
  
 <code bash> <code bash>
-sudo apt-get install ruby2.0 ruby2.0-dev libssl-dev make g+++gem install vpsfree-client
 </code> </code>
  
-=== A Quick & Dirty Fix to Set Ruby2.0 as Default Instead of 1.9 === +Platform-specific instructions:
- +
-<code bash> +
-sudo rm /usr/bin/ruby /usr/bin/gem /usr/bin/irb /usr/bin/rdoc /usr/bin/erb +
-sudo ln -s /usr/bin/ruby2.0 /usr/bin/ruby +
-sudo ln -s /usr/bin/gem2.0 /usr/bin/gem +
-sudo ln -s /usr/bin/irb2.0 /usr/bin/irb +
-sudo ln -s /usr/bin/rdoc2.0 /usr/bin/rdoc +
-sudo ln -s /usr/bin/erb2.0 /usr/bin/erb +
-sudo gem update --system +
-sudo gem pristine --all +
-</code> +
- +
-Source: http://blog.costan.us/2014/04/restoring-ruby-20-on-ubuntu-1404.html +
- +
-=== Installing vpsfree-client === +
- +
-<code bash> +
-sudo gem install vpsfree-client +
-</code> +
- +
- +
-----+
  
 +  * [[manuals:vps:api:macos|macOS]]
 +  * [[manuals:vps:api:windows|Windows]]
  
-After the installation,  ''vpsfreectl'' should be available in ''$PATH''. If not,+After the installation, ''vpsfreectl'' should be available in ''$PATH''. If not,
 this can be fixed easily: this can be fixed easily:
  
Line 130: Line 107:
  
 <code> <code>
-$ PATH="$PATH:/home/user/.gem/ruby/2.0.0/bin"+$ PATH="$PATH:/home/user/.gem/ruby/3.0.0/bin"
 </code> </code>
  
-==== Usage ====+==== Using CLI ====
  
 <code> <code>
Line 165: Line 142:
  
 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 165:
 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 178:
 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 210:
 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 261:
     -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
 +        --scope [SCOPE]              Scope
         --token TOKEN                Token         --token TOKEN                Token
         --token-lifetime LIFETIME    Token lifetime, defaults to renewable_auto         --token-lifetime LIFETIME    Token lifetime, defaults to renewable_auto
Line 280: Line 308:
 access to ''~/.haveapi-client.yml'' can access and use the token. access to ''~/.haveapi-client.yml'' can access and use the token.
 </note> </note>
 +
 +Specify a scope:
 +
 +<code>
 +$ vpsfreectl --auth token --scope 'vps#*:vps_id=123' --save vps show 123
 +</code>
 +
 +The command above will ask for an authentication token that will only be allowed to call actions on the vps resource and only on VPS with ID 123.
  
 ==== Actions and Parameters ==== ==== Actions and Parameters ====
Line 536: Line 572:
 <note> <note>
 Although these examples are still valid, the CLI client already contains Although these examples are still valid, the CLI client already contains
-[[navody:vps:datasety#stahovani_zaloh|commands]] which make downloading backups+[[manuals:vps:datasets#downloading_backups|commands]] which make downloading backups
 even easier. even easier.
 </note> </note>
Line 546: Line 582:
 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')
- 
-downloads = [] 
  
 api.dataset.list(role: :hypervisor).each do |ds| api.dataset.list(role: :hypervisor).each do |ds|
   last_snapshot = ds.snapshot.list.last   last_snapshot = ds.snapshot.list.last
  
 +  # This action may take up to several hours
   dl = api.snapshot_download.create(snapshot: last_snapshot.id)   dl = api.snapshot_download.create(snapshot: last_snapshot.id)
-  +
   unless dl.api_response.ok?   unless dl.api_response.ok?
     warn "#{ds.name}@#{last_snapshot.created_at}: #{dl.api_response.message}"     warn "#{ds.name}@#{last_snapshot.created_at}: #{dl.api_response.message}"
     next     next
   end   end
 +  
 +  # The file is ready for download
 +  puts "Downloading #{id} to #{dl.file_name} (#{dl.size / 1024} GB)"
 +  `wget #{dl.url}`
  
-  downloads << dl.id +  # Finally, delete the file from the server 
-end +  dl.delete
- +
-# vpsAdmin is now creating a tar.gz with the backup and it will take a while until it can be +
-# downloaded. There are regular checks for the “ready” parameter for all archives. +
-puts "Waiting for the downloads to be ready..." +
-loop do +
-  sleep(5*60) +
- +
-  downloads.delete_if do |id| +
-    dl = api.snapshot_download.find(id) +
-   +
-    unless dl.api_response.ok? +
-      warn "Download #{id} has failed" +
-      next(true)  # remove from the list +
-    end +
-   +
-    if dl.ready +
-      puts "Downloading #{id} to #{dl.file_name} (#{dl.size / 1024} GB)" +
-      `wget "#{dl.url}"` +
-      dl.delete +
-      true +
-   +
-    else +
-      false +
-    end +
-  end +
-   +
-  break if downloads.empty?+
 end end
  
Line 601: Line 613:
 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 607: Line 619:
   # Creating a new snapshot   # Creating a new snapshot
   ds.snapshot.create   ds.snapshot.create
- 
-  # Naive waiting until the snapshot is created. A different option would be checking 
-  # the state of the corresponding transaction chain. 
-  sleep(10) 
  
   # Deleting older snapshots   # Deleting older snapshots
Line 626: Line 634:
       snap.delete       snap.delete
       deleted += 1       deleted += 1
- 
-      # Once again, naive waiting until the action finishes. 
-      sleep(30) 
     end     end
   end   end
manuals/vps/api.1481467455.txt.gz · Last modified: 2016/12/11 14:44 by toms

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki