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

Both sides previous revisionPrevious revision
Next revision		Previous revision
manuals:vps:api [2019/05/17 14:03] – Aithermanuals:vps:api [2025/03/24 20:40] (current) – Fix API doc link aither
Line 8: Line 8:
 ===== 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/v5.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 26: Line 26:
   * JavaScript - https://github.com/vpsfreecz/haveapi/tree/master/clients/js   * JavaScript - https://github.com/vpsfreecz/haveapi/tree/master/clients/js
   * Go - https://github.com/vpsfreecz/haveapi/tree/master/clients/go   * Go - https://github.com/vpsfreecz/haveapi/tree/master/clients/go
-  * The HaveAPI web interface - https://github.com/vpsfreecz/haveapi-webui +  * The HaveAPI web interface - https://github.com/vpsfreecz/haveapi-webui (outdated) 
-  * A file system based on FUSE - https://github.com/vpsfreecz/haveapi-fs+  * 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 38: 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 +  * [[#http_basic|HTTP Basic]] 
-the client first requests a token to be created, one for which the client needs +  * [[#tokens|Using tokens]] 
-the name, password and possibly TOTP. As soon as the client receives the token, + 
-the name and password can be forgotten since it is the token that is then used +Example usage in different programming languages can be found in [[https://api.vpsfree.cz/v6.0/#auth|API documentation]]. 
-for further authentication.+ 
 +==== 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 The type of token and time period by which its validity is extended is chosen
 by the client. by the client.
  
-===== CLI ===== +===== Scopes ===== 
-[[https://github.com/vpsfreecz/vpsfree-client|The Ruby client]] also includes a CLI. +Authentication tokens can be restricted to selected actions. Each action has its own scope, 
-In order for it to work properly, you need Ruby >= 2.0 and Ruby header files, +you can find the available scopes in the documentation. You can configure scopes when you're 
-OpenSSL and ncurses (mostly packages with the ''-dev'' or ''-devel'' suffix)+requesting a new authentication token.
  
-<note> +Example scopes:
-If you’re using OS X, you first need to install OpenSSL using [[http://brew.sh/|Homebrew]] and only then +
-can you install EventMachine (a gem required by the client).+
  
-<code> +  * ''all'' allow access to all actions, this is used by the web interface and it is the default scope 
-$ brew install openssl +  *  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 
-$ sudo gem install eventmachine -- --with-opt-include="/usr/local/opt/openssl/" +  * ''vps#show'' allow access to action show on vps resource 
-</code> +  * ''vps#show:vps_id=123'' allow access to action show on a specific VPS 
-</note>+  * ''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
  
-It can be installed using ruby gems:+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.
  
-<code> +===== Installing vpsfree-client ===== 
-$ gem install vpsfree-client +[[https://github.com/vpsfreecz/vpsfree-client|The Ruby client]] also includes a CLI. 
-</code> +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).
- +
-==== Installing in Windows 10 Using a Ubuntu Linux Subsystem ==== +
- +
-=== Installing Ubuntu (Windows 10 Subsystem for Linux) === +
- +
-  - in Windows 10, enable Developer Mode, let it install +
-  - 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 +
-  - after the restart, run bash in the Start menu as admin +
-  - 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 132: 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 288: Line 263:
         --user 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 332: 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 ====
manuals/vps/api.1558101791.txt.gz · Last modified: 2019/05/17 14:03 by Aither

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