Naše API běží na adrese https://api.vpsfree.cz. Pomocí API lze vykonat většinu akcí, stejně jako z webového rozhraní. V API aktuálně není zahrnuta pouze správa uživatelských profilů (adresa, e-mail, apod.) a datové přenosy.

Ve skutečnosti webové rozhraní běžící na https://vpsadmin.vpsfree.cz API využívá a pro každý úkon jej volá.

Dokumentace API, tzn. seznam objektů, možných akcí, vstupních a výstupních parametrů je k vidění na https://api.vpsfree.cz/v1/.

Bez přihlášení se zobrazuje seznam všech objektů, tj. i těch, se kterými můžou pracovat pouze administrátoři. Vpravo nahoře se lze přihlásit stejnými údaji jako do vpsAdminu a poté se zobrazí pouze objekty, akce a parametry, se kterými může aktuálně přihlášený uživatel pracovat.

API je postaveno na námi vyvinutém frameworku HaveAPI, které vytváří samodokumentující se API, což znamená, že lze využít předpřipravené generické klienty:

• Ruby - https://github.com/vpsfreecz/vpsfree-client
• PHP - https://github.com/vpsfreecz/haveapi-client-php
• JavaScript - https://github.com/vpsfreecz/haveapi-client-js

Ukázka použití je vždy v README.md každého klienta. Obecně se klientovi předá URL k API, poté si sám stáhne dokumentaci a podle ní se nastaví.

API je RESTful, takže pro jednoduché úkony lze využít i libovolný REST klient. Popis vlastního protokolu pro přenos dat, který HaveAPI klienti abstrahují, je k nahlédnutí v dokumentaci.

Lze využívat dvě autentizační metody. Tou první a jednodušší z nich je HTTP basic. S každým požadavkem na API se musí zaslat jméno a heslo. Je to dobrá volba pro jednorázové akce, pokud je ale potřeba API volat vícekrát nebo automatizovaně, ukládání hesla na disk či neustálé opisování není dobrý nápad.

Druhou metodou je autentizace přes tokeny. Funguje to tak, že klient nejprve požádá o vytvoření tokenu, k tomu potřebuje jméno a heslo. Jakmile dostane token, může jméno a heslo zapomenout a dále se autentizuje získaným tokenem.

Tokeny mohou být několika typů s různě dlouhou životností:

• fixed - platnost tokenu je pevně dána
• renewable_manual - platnost tokenu lze manuálně prodloužit
• renewable_auto - platnost tokenu je prodloužena při každém požadavku
• permament - token je platný napořád, resp. dokud není smazán

Typ tokenu a časový interval, o který se prodlužuje, si volí klient.

Klient pro Ruby obsahuje i CLI. Pro správnou funkci vyžaduje Ruby >= 2.0.

Nainstalovat jej lze pomocí ruby gems:

$ gem install vpsfree-client

Po instalaci by v $PATH měl být k dispozici vpsfreectl. Pokud tomu tak není, lze to jednoduše napravit:

$ gem env | grep "EXECUTABLE DIRECTORY"

Tento příkaz vypíše, kde jsou uloženy spustitelné soubory instalované přes gem. Stačí tedy onen adresář přidat do $PATH, např.:

$ PATH="$PATH:/home/user/.gem/ruby/2.0.0/bin"

$ vpsfreectl --help
Usage: vpsfreectl [options] <resource> <action> [objects ids] [-- [parameters]]
    -u, --api URL                    API URL
    -a, --auth METHOD                Authentication method
        --list-versions              List all available API versions
        --list-auth-methods [VERSION]
                                     List available authentication methods
        --list-resources [VERSION]   List all resource in API version
        --list-actions [VERSION]     List all resources and actions in API version
        --version VERSION            Use specified API version
    -r, --raw                        Print raw response as is
    -s, --save                       Save credentials to config file for later use
    -v, --[no-]verbose               Run verbosely
        --client-version             Show client version
    -h, --help                       Show this message

Available resources:
auth_token
cluster
cluster_resource
dataset
dataset.snapshot
dataset.plan
dataset_plan
dns_resolver
environment
environment.config_chain
environment.dataset_plan
integrity_check
integrity_fact
integrity_object
ip_address
location
mail_log
mail_recipient
mail_template
mail_template.recipient
node
os_template
pool
snapshot_download
transaction_chain
transaction_chain.transaction
user
user.environment_config
user.cluster_resource
user.state_log
user_session
vps
vps.state_log
vps.config
vps.feature
vps.ip_address
vps.mount
vps.console_token
vps_config

Výběrem autentizační metody nebo objektu či akce v nápovědě přibydou další možné přepínače:

$ vpsfreectl --auth basic --help
$ vpsfreectl vps --help
$ vpsfreectl vps list --help

Jméno a heslo buď předáme parametry --username a --password, nebo parametry vynecháme a program k zadání údajů uživatele vybídne.

$ vpsfreectl --auth basic user current

Autentizace přes tokeny zavádí několik nových přepínačů:

$ vpsfreectl --auth token --help
    ...
    -a, --auth METHOD                Authentication method
    -s, --save                       Save credentials to config file for later
        --username USER              User name
        --password PASSWORD          Password
        --token TOKEN                Token
        --token-lifetime LIFETIME    Token lifetime, defaults to renewable_auto
        --token-interval SECONDS     How long will token be valid in seconds
        --new-token                  Request new token
        --token-via VIA              Send token as a query parameter or in HTTP header (query_param, header)
    ...

Jméno a heslo opět nemusíme předávat jako parametry, program se na ně zeptá.

Jednorázový token:

$ vpsfreectl --auth token user current

Po ukončení je token zapomenut a příště je nutné vyžádat další. Token pro takové použití postráda smysl.

Uložení tokenu:

$ vpsfreectl --auth token --save user current

Token se uložil do souboru ~/.haveapi-client.yml a při dalším spuštění je automaticky načten:

$ vpsfreectl user current

Takový token ale do 20 minut expiruje a je nutné vyžádat si nový. Je možné si rovnou udělat token s delší platností:

$ vpsfreectl --auth token --save --token-interval $((24*60*60)) user current # 1 den

Nebo rovnou token s platností neomezenou:

$ vpsfreectl --auth token --save --token-lifetime permanent user current

Objekty a akce mají názvy stejné jako v dokumentaci, jen malými písmeny a místo mezer podtržítka. Každá akce má svoje vstupní a výstupní parametry. Ty vstupní nám zobrazí --help, pokud je zadán název objektu i akce:

$ vpsfreectl vps list --help
...
Action description:
List VPS

Action parameters:
        --offset OFFSET              The offset of the first object
        --limit LIMIT                The number of objects to retrieve
        --node NODE                  Filter by node
        --location LOCATION          Filter by location
        --environment ENVIRONMENT    Filter by environment
        --os-template OS_TEMPLATE    OS template
        --object-state OBJECT_STATE  Object state
    -h, --help                       Show this message
...

Můžeme tedy VPS filtrovat dle serveru, lokace, prostředí, distribuce, stavu a omezit počet zobrazených položek či stránkovat.

Parametry akcí jsou od parametrů klienta odděleny dvěmi pomlčkami --. Následující příkaz vypíše první tři VPS:

$ vpsfreectl vps list -- --limit 3

Pokud bychom chtěli filtrovat např. dle lokace, nejdříve si je vypíšeme:

$ vpsfreectl location list
ID | LABEL     
---|-----------
3  | Praha     
4  | Brno      
5  | Playground

Nyní zobrazíme VPS nacházející se v lokaci Praha:

$ vpsfreectl vps list -- --location 3

Následují skripty demonstrují možnosti využití API. Tyto skripty lze spouštět odkudkoli, manuálně, z cronu, apod.

#!/usr/bin/env ruby
# Download latest backup of all VPSes.
require 'vpsfree/client'

api = Vpsfree::Client::Client.new
api.authenticate(:token, token: 'PUT YOUR TOKEN HERE')

downloads = []

api.dataset.list(role: :hypervisor).each do |ds|
  last_snapshot = ds.snapshot.list.last

  dl = api.snapshot_download.create(snapshot: last_snapshot.id)
  
  unless dl.api_response.ok?
    warn "#{ds.name}@#{last_snapshot.created_at}: #{dl.api_response.message}"
    next
  end

  downloads << dl.id
end

# Creation of the archives is now queued, it will take some time before they're
# ready to download. Regularily check dl.ready.
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

puts "Done"

#!/usr/bin/env ruby
# Daily snapshots of NAS with 7 day history
require 'vpsfree/client'

api = Vpsfree::Client::Client.new
api.authenticate(:token, token: 'PUT YOUR TOKEN HERE')

api.dataset.list(role: :primary).each do |ds|
  # Make a new snapshot
  ds.snapshot.create

  # Rotate old snapshots
  t = Time.now - 7 * 24 * 60 * 60
  snapshots = ds.snapshot.list(meta: {count: true})
  deleted = 0
  
  snapshots.each do |snap|
    # Keep at least 7 snapshots
    break if snapshots.total_count - deleted < 7
    
    # Delete snapshots older than one week
    if snap.created_at < t
      puts "Delete #{ds.name}@#{snap.created_at}"
      snap.delete
      deleted += 1
    end
  end
end